You are on page 1of 442

Oracle Fusion Middleware

1[]

System Administrator's Guide for Oracle Business Intelligence


Enterprise Edition
12c (12.2.1)
E57379-03

December 2015
Explains how to manage Oracle Business Intelligence
Enterprise Edition processes and components, including how
to start and stop, configure, and extend deployments.
Includes how to customize, monitor, troubleshoot, and
migrate an Oracle Business Intelligence Enterprise system.
Oracle Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition,
12c (12.2.1)

E57379-03

Copyright 2010, 2015, Oracle and/or its affiliates. All rights reserved.

Primary Author: Nick Fry

Contributing Authors: Marla Azriel, Christine Jacobs, Dona Hobin, Cammy Moore, Stefanie Rhone, Lea
Shaw.

Contributors: Oracle Business Intelligence development, product management, and quality assurance teams.

This software and related documentation are provided under a license agreement containing restrictions on
use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your
license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,
transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse
engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is
prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If
you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it
on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software,
any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users
are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and
agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and
adaptation of the programs, including any operating system, integrated software, any programs installed on
the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to
the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management
applications. It is not developed or intended for use in any inherently dangerous applications, including
applications that may create a risk of personal injury. If you use this software or hardware in dangerous
applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other
measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages
caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of
their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks
are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD,
Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced
Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content,
products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and
expressly disclaim all warranties of any kind with respect to third-party content, products, and services
unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its
affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of
third-party content, products, or services, except as set forth in an applicable agreement between you and
Oracle.
Contents

Preface .............................................................................................................................................................. xix


Audience.................................................................................................................................................... xix
Documentation Accessibility .................................................................................................................. xix
Related Documentation and Other Resources ...................................................................................... xx
Conventions ............................................................................................................................................... xx

New Features for Oracle Business Intelligence System Administrators ............... xxi
New Features and Changes for Oracle BI EE 12c (12.2.1)................................................................... xxi

Part I Administering Oracle Business Intelligence

1 Introduction to Oracle Business Intelligence System Administration


What Are the Oracle Business Intelligence System Administration Tasks?................................ 1-1
Getting Started with Managing Oracle Business Intelligence........................................................ 1-2
What Is the Oracle Business Intelligence System Logical Architecture? ...................................... 1-3
Oracle Business Intelligence System Architecture ........................................................................ 1-4
Oracle Business Intelligence Components...................................................................................... 1-4
About the Administration Server, Managed Servers, and System Components ..................... 1-5
About the Administration Server and Managed Servers...................................................... 1-5
About System Components....................................................................................................... 1-6
Key Directories in Oracle Business Intelligence................................................................................ 1-6
What System Administration Tools Manage Oracle Business Intelligence? ............................... 1-7
Fusion Middleware Control ............................................................................................................. 1-7
Oracle WebLogic Server Administration Console ........................................................................ 1-8
Process Control Commands ............................................................................................................. 1-8
Oracle WebLogic Scripting Tool (WLST)........................................................................................ 1-8
Oracle BI Administration Tool ......................................................................................................... 1-9
Catalog Manager ................................................................................................................................ 1-9
Job Manager ........................................................................................................................................ 1-9
Working with the Sample Application ................................................................................................ 1-9
Oracle BI Publisher Integration ............................................................................................................ 1-9
Topics of Interest in Other Guides ....................................................................................................... 1-9
System Requirements and Certification........................................................................................... 1-10

Part II Managing Processes and Components

iii
2 Managing Oracle Business Intelligence Processes
About Managing Oracle Business Intelligence Processes ............................................................... 2-1
Conditions for Starting the Oracle Business Intelligence System ................................................. 2-2
Using Commands to Stop, Start, and View Status of Oracle Business Intelligence Processes 2-2
Stopping Oracle Business Intelligence Component Processes in a Domain ............................. 2-2
Starting Oracle Business Intelligence Component Processes in a Domain................................ 2-3
Viewing the Status of Oracle Business Intelligence Components in a Domain........................ 2-4
Using Fusion Middleware Control to Start and Stop BI System Component Processes ........... 2-5
Using Fusion Middleware Control to Start and Stop Java Components ...................................... 2-5
Using Oracle WebLogic Server Administration Console to Start and Stop Java Components 2-7

Part III Scaling and Deploying for High Availability and Performance

3 Scaling Your Deployment


About Scaling Oracle Business Intelligence....................................................................................... 3-1
How Do I Know When to Scale Out Processes? ............................................................................ 3-2
What Processes Should I Scale? ....................................................................................................... 3-2
Setting Up Shared Files and Directories.............................................................................................. 3-3
Changing the Singleton Data Directory (SDD).............................................................................. 3-3
Setting Up the Global Cache............................................................................................................. 3-4
Managing Capacity in Oracle Business Intelligence (Vertically Scaling) .................................... 3-4
Adding System Components............................................................................................................ 3-5
Removing System Components ....................................................................................................... 3-6
Managing Availability in Oracle Business Intelligence (Horizontally Scaling) ......................... 3-7
Adding New Computers................................................................................................................... 3-7
Removing Existing Computers ........................................................................................................ 3-9
Validating That Your System Has Been Scaled Correctly............................................................. 3-10
Using Fusion Middleware Control to View System Component Availability ...................... 3-10
Using the Administration Console to View Managed Server Availability ............................ 3-11

4 Deploying Oracle Business Intelligence for High Availability


About Oracle Business Intelligence Components in a Clustered Environment ......................... 4-1
Recommendations for Availability.................................................................................................. 4-2
Using Fusion Middleware Control to Identify Single Points of Failure .................................... 4-3
Achieving High Availability Using an Active-Passive Model .................................................... 4-3
Configuring Oracle Business Intelligence Components for High Availability .......................... 4-4
Optional Configuration for Oracle Business Intelligence High Availability.............................. 4-4
Setting Optional Cluster Controller Parameters............................................................................ 4-4
Setting Optional Presentation Services Parameters ...................................................................... 4-5
Setting Optional Oracle BI Presentation Services Plug-in Parameters....................................... 4-5
Using the Cluster Manager..................................................................................................................... 4-6
Viewing and Managing Cluster Information................................................................................. 4-7
Status Information ...................................................................................................................... 4-7
Cache Information ...................................................................................................................... 4-8
Session Information .................................................................................................................... 4-9
Server Information................................................................................................................... 4-10

iv
Troubleshooting an Oracle Business Intelligence Clustered Environment .............................. 4-11
Avoiding Errors with Network Appliance Devices When the Oracle BI Server Is
Running on Linux or UNIX ........................................................................................................... 4-11

5 Managing Performance Tuning and Query Caching


Monitoring Service Levels...................................................................................................................... 5-1
Using Fusion Middleware Control to View All Oracle Business Intelligence Metrics............ 5-2
Using the Administration Console to View Metrics for Java Components............................... 5-2
About Query Performance Tuning ....................................................................................................... 5-3
Setting Performance Parameters in Fusion Middleware Control................................................... 5-4
Using Fusion Middleware Control to Disallow RPD Updates ................................................... 5-4
Using Fusion Middleware Control to Set the User Session Log-Off Period ............................. 5-5
Using Fusion Middleware Control to Set Configuration Options for Data in Tables
and Pivot Tables ................................................................................................................................. 5-5
Using Fusion Middleware Control to Set the Maximum Number of Rows Processed
to Render a Table................................................................................................................................ 5-6
About the Oracle BI Server Query Cache............................................................................................ 5-7
Query Cache Architecture ................................................................................................................ 5-7
Advantages of Caching ..................................................................................................................... 5-8
Costs of Caching................................................................................................................................. 5-8
Disk Space .................................................................................................................................... 5-9
Administrative Tasks ................................................................................................................. 5-9
Keeping the Cache Up To Date................................................................................................. 5-9
CPU Usage and Disk I/O .......................................................................................................... 5-9
Cache Sharing Across Users ............................................................................................................. 5-9
About the Refresh Interval for XML Data Sources..................................................................... 5-10
About the Global Cache ................................................................................................................. 5-10
Configuring Query Caching................................................................................................................ 5-12
Using Fusion Middleware Control to Enable and Disable Query Caching ........................... 5-12
Using Fusion Middleware Control to Set Query Cache Parameters ....................................... 5-13
Manually Editing Additional Query Cache Parameters ........................................................... 5-13
Using Fusion Middleware Control to Set Global Cache Parameters ...................................... 5-14
Manually Editing Additional Global Cache Parameters........................................................... 5-14
Monitoring and Managing the Cache ............................................................................................... 5-14
Choosing a Cache Management Strategy .................................................................................... 5-15
Disable Caching for the System ............................................................................................. 5-15
Caching and Cache Persistence Timing for Specified Physical Tables ............................ 5-15
Configure Oracle BI Server Event Polling Tables ............................................................... 5-15
Purging and Maintaining Cache Using ODBC Procedures ...................................................... 5-16
About ODBC Procedure Syntax............................................................................................. 5-17
About Sharing the Presentation Services Query Cache ..................................................... 5-17
About Result Records.............................................................................................................. 5-17
Storing and Purging Cache for SAP/BW Data Sources ..................................................... 5-18
How Repository Changes Affect the Query Cache.................................................................... 5-19
Online Mode ............................................................................................................................. 5-19
Offline Mode............................................................................................................................. 5-19
Switching Between Repositories............................................................................................ 5-19

v
Changes to Dynamic Repository Variables.......................................................................... 5-20
Strategies for Using the Cache............................................................................................................ 5-20
About Cache Hits ............................................................................................................................ 5-20
Ensuring Correct Cache Results When Using Row-Level Database Security ................ 5-22
Running a Suite of Queries to Populate the Cache .................................................................... 5-23
Using Agents to Seed the Oracle BI Server Cache...................................................................... 5-24
Using the Cache Manager .............................................................................................................. 5-24
Displaying Global Cache Information in the Cache Manager .......................................... 5-26
Purging Cache in the Administration Tool .......................................................................... 5-26
Cache Event Processing with an Event Polling Table.................................................................... 5-27
Setting Up Event Polling Tables on the Physical Databases..................................................... 5-28
Making the Event Polling Table Active ....................................................................................... 5-30
Populating the Oracle BI Server Event Polling Table ................................................................ 5-31
Troubleshooting Problems with Event Polling Tables .............................................................. 5-31
Managing the Oracle BI Presentation Services Cache Settings ................................................... 5-31
Improving Oracle BI Web Client Performance ............................................................................... 5-33
Configuring Apache HTTP Server for Static File Caching........................................................ 5-33
Configuring Oracle HTTP Server for Static File Caching ......................................................... 5-36
Setting the JVM Heap Size for Oracle Business Intelligence ...................................................... 5-36
Capturing Metrics Using the Dynamic Monitoring Service......................................................... 5-36
Using the Dynamic Monitoring Service for Metrics .................................................................. 5-37
Using WLST Commands for Metrics ........................................................................................... 5-37

Part IV Resolving Issues

6 Diagnosing and Resolving Issues in Oracle Business Intelligence


What Diagnostic Tools Are Available?................................................................................................ 6-1
Collecting Diagnostic Bundles .............................................................................................................. 6-2
Viewing and Configuring Diagnostic Log Files ................................................................................ 6-3
Using Fusion Middleware Control to View Log Information, Error Messages, and Alerts ... 6-3
Configuring Log File Rotation Policy and Specifying Log Levels.............................................. 6-4
Using Fusion Middleware Control to Configure Log File Rotation Policy and
Specify Log Levels ...................................................................................................................... 6-4
Manually Changing Additional Log File Settings ................................................................. 6-5
Diagnosing Issues Using the Log Viewer....................................................................................... 6-5
Understanding Diagnostic Log and Log Configuration Files ......................................................... 6-7
What Are Diagnostic Log Files and Where Are They Located?.................................................. 6-7
What Are Diagnostic Log Configuration Files and Where Are They Located?........................ 6-8
What Are Log File Message Categories and Levels? ................................................................. 6-10
What is Log File Rotation? ............................................................................................................. 6-11
What Messages Are Included in the System Log? ..................................................................... 6-12
Managing the Query Log ..................................................................................................................... 6-12
Configuring Query Logging.......................................................................................................... 6-13
Setting the Query Logging Level........................................................................................... 6-13
Setting the Query Logging Level for a User ........................................................................ 6-15
Using the Log Viewer ..................................................................................................................... 6-15
Running the Log Viewer Utility ............................................................................................ 6-15

vi
Interpreting the Log Records ................................................................................................. 6-16
Logging in Oracle BI Presentation Services..................................................................................... 6-16
Using the Oracle BI Presentation Services Logging Facility..................................................... 6-17
Setting the Logging Levels for Oracle BI Presentation Services............................................... 6-17
Structure for the Oracle BI Presentation Services Configuration File ..................................... 6-17
Examples of the Formats of Logged Messages ........................................................................... 6-21
Oracle BI Presentation Services Message Structure ................................................................... 6-22
Oracle BI Presentation Services Log Filters................................................................................. 6-22
Diagnosing Issues with Agents..................................................................................................... 6-23
Debugging Agents Using Fusion Middleware Control ..................................................... 6-23
Manually Debugging Agents Using instanceconfig.xml ................................................... 6-24
Using ODBC/JDBC Procedures to Obtain Oracle BI Server Diagnostics .................................. 6-25
About the Oracle BI Server ODBC/JDBC Procedures............................................................... 6-25
Obtaining a List of Available Diagnostic Categories ................................................................. 6-25
Running Specific Diagnostics ........................................................................................................ 6-26
About Parameters for ODBC/JDBC Procedures........................................................................ 6-27
Troubleshooting System Startup ....................................................................................................... 6-29
Administration Server Fails to Start When the Database Is Not Running ............................. 6-29
Managed Server Is Down............................................................................................................... 6-29
Oracle BI Server Fails to Start ........................................................................................................ 6-29
Cannot Log In .................................................................................................................................. 6-29

7 Managing Usage Tracking


About Usage Tracking............................................................................................................................. 7-1
Setting Up Direct Insertion to Collect Information for Usage Tracking....................................... 7-2
Setting Up the Usage Tracking Statistics Database....................................................................... 7-2
Setting Direct Insertion Parameters................................................................................................. 7-2
Setting Optional Direct Insert Parameters...................................................................................... 7-3
Description of the Usage Tracking Data.............................................................................................. 7-4

Part V Configuring Oracle Business Intelligence

8 Using Tools for Managing and Configuring Oracle Business Intelligence


Why Use Fusion Middleware Control and WebLogic Server Administration Console? .......... 8-1
Managing Oracle Business Intelligence System Components Using
Fusion Middleware Control ................................................................................................................... 8-2
Logging into Fusion Middleware Control...................................................................................... 8-2
Displaying Oracle Business Intelligence Pages in Fusion Middleware Control....................... 8-3
Using the Navigation Tree in Fusion Middleware Control ......................................................... 8-4
Tips for Using Fusion Middleware Control with Oracle Business Intelligence ....................... 8-4
Configuring Oracle Business Intelligence System Settings ............................................................ 8-5
Using Fusion Middleware Control.................................................................................................. 8-6
Using a Text Editor ............................................................................................................................ 8-7
Using the WebLogic Scripting Tool (WLST) .................................................................................. 8-7
Making Offline Configuration Changes .................................................................................. 8-7
Making Online Configuration Changes .................................................................................. 8-8

vii
Updating the Java Development Kit (JDK) .................................................................................... 8-9
Managing Oracle Business Intelligence Java Components Using the Oracle WebLogic Server
Administration Console.......................................................................................................................... 8-9

9 Managing Metadata and Working with Service Instances


About Oracle Business Intelligence Application Archive (BAR) Files ......................................... 9-1
What Are Oracle Business Intelligence Application Archive (BAR) Files? ............................... 9-1
What Predefined BAR Files are Available? .................................................................................... 9-1
About Importing BAR Files .............................................................................................................. 9-3
Managing Service Instances................................................................................................................... 9-3
listBIServiceInstances ........................................................................................................................ 9-4
getBIServiceInstance .......................................................................................................................... 9-5
scaleOutBIServiceInstance ................................................................................................................ 9-5
exportServiceInstance........................................................................................................................ 9-6
importServiceInstance ....................................................................................................................... 9-7
refreshServiceInstance ....................................................................................................................... 9-8
refreshDomainServiceInstances ....................................................................................................... 9-8
resetServiceInstance........................................................................................................................... 9-9

10 Configuring Connections to External Systems


Configuring Email and Agents........................................................................................................... 10-1
Using Fusion Middleware Control to Configure Oracle BI Scheduler Email
Settings that Affect Agents ............................................................................................................ 10-1
Configuring for Actions with the Action Framework.................................................................... 10-2
Configuring Connections to the Marketing Content Server ........................................................ 10-2
Configuring Connections to Data Sources....................................................................................... 10-3

11 Configuring Presentation Setting Defaults


Using Fusion Middleware Control to Change Presentation Setting Defaults.......................... 11-1

12 Configuring Mapping and Spatial Information


What Are the System Requirements for Map Views? ................................................................... 12-1
Hardware Sizing and Deployment Strategy for Maps .................................................................. 12-3
Administering Maps............................................................................................................................. 12-3
Working with Maps and Layers ................................................................................................... 12-3
Associating Layers with Columns......................................................................................... 12-3
Ordering Layers on Maps....................................................................................................... 12-4
Changes to Spatial Metadata Require Restart ..................................................................... 12-6
Administration Page Functions .................................................................................................... 12-6
Administering Maps Using Administration Pages.................................................................... 12-7
Handling the Translation of Layers in Maps .............................................................................. 12-8

13 Configuring Time Zones


Why and Where Are Time Zones Used?........................................................................................... 13-1
Setting Time Zones ............................................................................................................................... 13-2
What is the Precedence Order for Time Zones................................................................................ 13-3

viii
User-Preferred Time Zone ............................................................................................................. 13-3
Where Are Time Zone Specifications Stored?................................................................................. 13-3
Specifying Time Zone Values........................................................................................................ 13-4
Description of Time Zone Settings.................................................................................................... 13-4
Example: Configuration File Settings for Specifying the Time Zone......................................... 13-6

14 Localizing Oracle Business Intelligence


What Is Localization?............................................................................................................................ 14-1
What Components Are Translated? ............................................................................................. 14-1
Tasks for Localizing Oracle Business Intelligence Components.............................................. 14-2
Localizing Oracle BI Presentation Services...................................................................................... 14-3
Localizing the User Interface for Oracle BI Presentation Services........................................... 14-3
Understanding the Directory Structure for Localizing Presentation Services................ 14-3
Localizing Messages for Users' Preferred Currency........................................................... 14-4
Specifying the Default Language for the Sign-In Page....................................................... 14-4
Configuring the Languages and Locales for the Sign-In Page .......................................... 14-5
Specifying the Scaling of Numbers in Performance Tiles .................................................. 14-6
Specifying the Language in the URL..................................................................................... 14-7
Localizing Oracle BI Presentation Catalog Captions ................................................................. 14-8
Step 1: Understanding the Export Process ........................................................................... 14-8
Step 2: Exporting Text Strings in the Catalog ...................................................................... 14-9
Step 3: Editing Exported Strings in XML Files .................................................................. 14-10
Step 4: Handling Duplicate Exported Text Strings ........................................................... 14-10
Step 5: Exposing Text Strings in the Catalog ..................................................................... 14-12
Tip for Arabic and Hebrew in Mozilla Firefox Browsers........................................................ 14-13
Setting the Current Locale in Catalog Manager ............................................................................ 14-13
Setting the Current Locale in the Oracle BI Server ...................................................................... 14-14
Setting Locale Parameters on the Oracle BI Server .................................................................. 14-14
Setting the Locale on UNIX Systems................................................................................... 14-15
Understanding How the Error Message Language Is Determined ....................................... 14-16
Setting the Language for Components of the Oracle BI Server.............................................. 14-17
Modifying the Language of the User Interface for the Administration Tool ....................... 14-17
Troubleshooting the Current Locale in the Oracle BI Server.................................................. 14-17
Handling the NLS Locale Not Supported Error Message ............................................... 14-18
Setting the Japanese Locale on AIX Systems ..................................................................... 14-18
Ensuring That Text for Oracle BI Server Utilities is Displayed in the Correct Language .. 14-18
Modifying the Metadata Repository When the Underlying Oracle Database NLS_
CHARACTERSET Is Not Unicode ............................................................................................. 14-18
Localizing Metadata Names in the Repository ............................................................................. 14-19
Supporting Multilingual Data.......................................................................................................... 14-21
What is Multilingual Data Support? .......................................................................................... 14-21
What is Lookup?............................................................................................................................ 14-21
What is Double Column Support?.............................................................................................. 14-22
Designing Translation Lookup Tables in a Multilingual Schema.......................................... 14-22
A Lookup Table for Each Base Table .................................................................................. 14-22
A Lookup Table for Each Translated Field ........................................................................ 14-22
Creating Logical Lookup Tables and Logical Lookup Columns ........................................... 14-23

ix
Creating Logical Lookup Tables.......................................................................................... 14-23
Designating a Logical Table as a Lookup Table ................................................................ 14-24
About the LOOKUP Function Syntax................................................................................. 14-24
Creating Logical Lookup Columns ..................................................................................... 14-25
Creating Physical Lookup Tables and Physical Lookup Columns........................................ 14-27
Supporting Multilingual Data in Essbase Through Alias Tables........................................... 14-28
Enabling Lexicographical Sorting............................................................................................... 14-28

15 Configuring Currency Options


Changing the Default Currency for Analyses ................................................................................. 15-1
Defining User-Preferred Currency Options..................................................................................... 15-2
Defining User-Preferred Currency Options Using a Static Mapping ..................................... 15-4
Example: Static Mapping to Define User-Preferred Currency Options.................................. 15-5
Defining User-Preferred Currency Options Using a Dynamic Mapping ............................... 15-6
Example: Dynamic Mapping to Define User-Preferred Currency Options ........................... 15-7

16 Configuring and Managing the Oracle BI Presentation Catalog


About the Oracle BI Presentation Catalog ....................................................................................... 16-1
Objects in the Catalog ..................................................................................................................... 16-1
Guidelines for Object Names ................................................................................................. 16-2
Attribute Files for Objects ....................................................................................................... 16-3
Lock Files for Objects............................................................................................................... 16-3
File System Guidelines for Catalogs............................................................................................. 16-3
Handling Users of the Catalog............................................................................................... 16-3
Handling Heterogeneous Nodes ........................................................................................... 16-4
Handling Catalog Files on Various Platforms ..................................................................... 16-4
Known Issues with Catalog Files........................................................................................... 16-5
Maintaining the Oracle BI Presentation Catalog ............................................................................ 16-5
Manually Changing Configuration Settings for the Catalog.................................................... 16-5
Deploying Catalogs and Objects to Production.......................................................................... 16-7
Deploying Catalogs to Production ........................................................................................ 16-7
Deploying Objects to Production........................................................................................... 16-7
Updating Catalog Objects .............................................................................................................. 16-8
Validating the Catalog.................................................................................................................... 16-8
Process: Validating the Catalog ............................................................................................. 16-9
Tasks in the Validation Process ............................................................................................. 16-9
Important Guidelines for Validating the Catalog ............................................................... 16-9
Performing a Basic Validation of the Catalog...................................................................... 16-9
Specifying the Elements for Validating the Catalog ......................................................... 16-10
About Catalog Manager ..................................................................................................................... 16-12
Uses for Catalog Manager............................................................................................................ 16-12
Guidelines for Working with Catalog Manager ....................................................................... 16-12
Tips for Working with Catalog Manager................................................................................... 16-12
Starting Catalog Manager and Opening Catalogs ........................................................................ 16-13
Requirements for Running Catalog Manager ........................................................................... 16-13
Starting the Catalog Manager User Interface............................................................................ 16-13
Resolving Startup Issues on Linux Systems.............................................................................. 16-14

x
Understanding the Two Catalog Modes ................................................................................... 16-14
Online Mode ........................................................................................................................... 16-15
Offline Mode........................................................................................................................... 16-15
Operations Available in Online Mode and Offline Mode....................................................... 16-15
Opening an Oracle BI Presentation Catalog.............................................................................. 16-16
Using the Catalog Manager Workspace.......................................................................................... 16-17
What Does the Catalog Manager Workspace Do? ................................................................... 16-17
What Does the Catalog Manager Workspace Look Like?....................................................... 16-18
Managing the View of the Catalog Manager Workspace ....................................................... 16-18
Working with Objects in Catalog Manager ................................................................................... 16-19
Searching for Catalog Objects Using Catalog Manager .......................................................... 16-19
Copying and Pasting Objects ..................................................................................................... 16-20
Tips for Copying and Pasting .............................................................................................. 16-20
Advanced Options for Pasting Objects............................................................................... 16-21
Renaming Catalog Objects........................................................................................................... 16-23
Working with the Properties of Catalog Objects ...................................................................... 16-24
Setting Permissions of Catalog Objects...................................................................................... 16-25
Previewing Objects from Catalog Manager .............................................................................. 16-26
Viewing and Editing Catalog Objects in XML.............................................................................. 16-26
Searching for and Replacing Catalog Text Using Catalog Manager......................................... 16-28
Searching for and Replacing a Simple Catalog Text String .................................................... 16-28
About Searching for and Replacing Multiple Catalog Text Strings ...................................... 16-28
XML File Format for Searching for and Replacing Text Strings ..................................... 16-29
Example XML File for Searching for and Replacing Text Strings .................................. 16-29
Searching for and Replacing Multiple Catalog Text Strings................................................... 16-30
Creating Reports to Display Catalog Data Using Catalog Manager ......................................... 16-30
Sample Uses for Reports .............................................................................................................. 16-31
Archiving and Unarchiving Using Catalog Manager................................................................... 16-31
Archiving a Folder Using Catalog Manager ............................................................................. 16-32
Unarchiving a Folder Using Catalog Manager......................................................................... 16-32

Part VI Advanced Configuration Settings

17 Configuring and Managing Analyses and Dashboards


Managing Dashboards ......................................................................................................................... 17-1
Performing General Configuration Tasks for Analyses................................................................ 17-2
Increasing Heap Size to Assist in Exports to Excel .................................................................... 17-2
Manually Configuring for Export................................................................................................. 17-3
Supporting Nested Folders, Navigation, and Drill-Down........................................................ 17-5
Configuring for Displaying and Processing Data in Views ......................................................... 17-5
Manually Configuring for Data in Views.................................................................................... 17-6
Manually Configuring Cube Settings for Pivot Tables and Graphs................................. 17-6
Manually Configuring Settings for Data in Views.............................................................. 17-6
Manually Configuring Settings for Fetching Data for Table Views,
Pivot Table Views, and Trellis Views.................................................................................. 17-10
Manually Configuring for Graphs and Gauges........................................................................ 17-11
Configuring Fonts for Graphs.............................................................................................. 17-13

xi
Configuring Graph and Gauge Rendering ........................................................................ 17-14
Manually Changing Alternating Bar Color............................................................................... 17-14
Manually Configuring for Interactions in Views ..................................................................... 17-15
Configuring for Prompts.................................................................................................................... 17-16
Manually Changing Presentation Settings .................................................................................... 17-19
Manually Changing Presentation Setting Defaults.................................................................. 17-19
Providing Custom Links in Presentation Services ................................................................... 17-22
Updating the customlinks.xml File ..................................................................................... 17-22
Adding the CustomLinks Element...................................................................................... 17-26
Setting the Custom Links Privilege ..................................................................................... 17-27
Enabling the Ability to Create Links to Dashboard Pages...................................................... 17-27
Configuring an Alternate Toolbar for Oracle BI Publisher..................................................... 17-28
Enabling the Ability to Export Dashboard Pages to Oracle BI Publisher ............................. 17-29
Modifying the Table of Contents for PDF Versions of Briefing Books ................................. 17-30
Configuring a Custom Download Link for the Smart View Installer ................................... 17-30
Blocking Analyses in Answers ......................................................................................................... 17-31
Storing JavaScript Files................................................................................................................. 17-31
Blocking Analyses Based on Criteria.......................................................................................... 17-31
Blocking Analyses Based on Formula ........................................................................................ 17-33
Validation Helper Functions ....................................................................................................... 17-34
Specifying View Defaults for Analyses and Dashboards........................................................... 17-35
XML Message Files for View Defaults ....................................................................................... 17-35
Examples of Customizing Default Values for Analyses and Dashboards............................ 17-35
Adding a Default Header or Footer to New Analyses ..................................................... 17-35
Preventing Auto-Previewing of Results ............................................................................. 17-36
Setting Defaults for Analyses in the Compound Layout ................................................. 17-37
Changing Dashboards Section Defaults ............................................................................. 17-37
Specifying Dashboard Page Defaults Including Headers and Footers .......................... 17-37
Configuring for Write Back in Analyses and Dashboards ......................................................... 17-38
How Write Back Works................................................................................................................ 17-39
Process for Configuring Write Back ........................................................................................... 17-39
Example: Process for Configuring Write Back.......................................................................... 17-40
Write-Back Limitations................................................................................................................. 17-41
Creating Write-Back Template Files........................................................................................... 17-42
Requirements for a Write-Back Template .......................................................................... 17-43
Examples: Write-Back Template Files................................................................................. 17-44
Setting the LightWriteback Element........................................................................................... 17-45
Customizing the Oracle BI Web User Interface ............................................................................ 17-45
What Are Skins and Styles? ......................................................................................................... 17-45
General Tips for Customizing the Web User Interface............................................................ 17-46
About Style Customizations ........................................................................................................ 17-46
Modifying the User Interface Styles for Presentation Services .............................................. 17-46
Approach 1: Deploying the "bicustom.ear" File for the First Time?............................... 17-47
Approach 1: Redeploying the "bicustom.ear" File ............................................................ 17-49
Approach 2: Deploying Using Shared Folders.................................................................. 17-49
Approach 2: Viewing Your Modifications to a Shared Folder ........................................ 17-52
Customizing Your Style ............................................................................................................... 17-52

xii
Example of Modifying the Skyros Master Branding Class ..................................................... 17-55
Embedding External Content in Dashboards ................................................................................ 17-56
Installing R and Oracle R Enterprise for External Logical SQL Functions.............................. 17-57
Installing R and R Packages......................................................................................................... 17-58
Before You Begin the Installation ........................................................................................ 17-58
Installing R and R Packages on UNIX Platforms .............................................................. 17-58
Installing R and R Packages on Windows.......................................................................... 17-59
Installing Oracle R Enterprise and Required R Packages on the Oracle Database ............. 17-59
Before You Begin the Installation ........................................................................................ 17-60
Installing Oracle R Enterprise and R Packages.................................................................. 17-60
Configuring Oracle R Enterprise to Work with Oracle BI EE ......................................... 17-60

18 Configuring and Managing Agents


How Are Agents Used? ........................................................................................................................ 18-1
How Do Antivirus Software and Privileges Affect Agents? ........................................................ 18-1
How Does Antivirus Software Affect Agents? ........................................................................... 18-2
What Privileges Affect Agents? .................................................................................................... 18-2
Configuring Settings that Affect Agents .......................................................................................... 18-2
Manually Configuring Presentation Services Settings that Affect Agents ............................ 18-3
Manually Changing Additional Scheduler Settings that Affect Agents ................................. 18-4
What Additional Scheduler Configuration Settings Affect Agents? ....................................... 18-4
General Scheduler Configuration Settings that Affect Agents.......................................... 18-4
Email Scheduler Configuration Settings that Affect Agents ............................................. 18-7
Agent Scheduler Configuration Settings.............................................................................. 18-7
Controlling Delivery Options for Agents .................................................................................... 18-9
Managing Device Types for Agents .................................................................................................. 18-9
Monitoring Active Agent Sessions .................................................................................................. 18-10

19 Configuring Advanced Options for Mapping and Spatial Information


Configuring MapViewer to Support Map Views ........................................................................... 19-1
Manually Configuring for Map Views ............................................................................................. 19-3
Inserting Text on a Map ....................................................................................................................... 19-4
Configuring Maps for External Consumption ................................................................................ 19-5

20 Configuring Resource Availability and URL Generation

Part VII Managing the Life Cycle

21 Patching Oracle Business Intelligence Systems


About Patching Oracle Business Intelligence Systems ................................................................. 21-1
Where Do I Find Complete Information on Patching?.............................................................. 21-1
Updating an Existing 12c BI Server Installation ......................................................................... 21-1
What Happens If a Patching Conflict Occurs?............................................................................ 21-2
What Is Patched for the Oracle Business Intelligence Platform? ................................................ 21-2
Rolling Back a Platform Patch ............................................................................................................ 21-3

xiii
Determining Current Patch Levels .................................................................................................... 21-3

22 Moving Oracle Business Intelligence Between Environments


Moving Between Environments......................................................................................................... 22-1
Moving to a New Environment .......................................................................................................... 22-3
Upgrading from 11g to 12c................................................................................................................... 22-3
Migrating the Whole Server................................................................................................................ 22-3

23 Backup and Recovery of Oracle Business Intelligence Systems

Part VIII Using Oracle Essbase With Oracle Business Intelligence

24 Introduction to Using Oracle Essbase and Associated Components in


Oracle Business Intelligence
Overview................................................................................................................................................. 24-1
High-Level Roadmap for Working with Essbase and Associated Tools in Oracle Business
Intelligence ............................................................................................................................................. 24-2
Performing Tasks on Essbase and Associated Tools in Oracle Business Intelligence Compared
to Performing the Same Tasks in EPM and Information on Which Guides to Consult ......... 24-2
Installing Essbase and Associated Components with Oracle Business Intelligence .............. 24-4
Installing Essbase ............................................................................................................................ 24-5
Selecting the Essbase Suite Option During Install ..................................................................... 24-5
Limitations for Using Client Tools when Essbase Is Installed with
Oracle Business Intelligence .......................................................................................................... 24-6
Essbase Features Not Supported when Essbase Is Installed with
Oracle Business Intelligence .......................................................................................................... 24-6
Changing Essbase Ports in Oracle Business Intelligence.............................................................. 24-6
Managing Essbase System Administration in Oracle Business Intelligence............................ 24-7
Starting and Stopping Essbase Components .............................................................................. 24-7
Maintaining High Availability of Essbase Components in Oracle Business Intelligence .... 24-7
Scaling Out Essbase to Support High Availability ............................................................. 24-8
About the Essbase Active-Passive Topology? ..................................................................... 24-8
Managing Essbase Capacity ................................................................................................... 24-8
Configuring Logging for Essbase Components.......................................................................... 24-8
Configuring Logging for EPM Components............................................................................. 24-10
Migrating Essbase Configuration Between Domains .............................................................. 24-14
Monitoring Essbase Metrics......................................................................................................... 24-14
Backup and Recovery of Essbase Data....................................................................................... 24-14
Working with Essbase Data in Oracle Business Intelligence..................................................... 24-14
Enabling Single Sign-On for Essbase Data Sources.................................................................. 24-14
Creating, Scheduling, and Running Analyses and Reports Where Essbase Is the
Data Source .................................................................................................................................... 24-15
Enabling Oracle BI EE to Connect to Essbase Over SSL.......................................................... 24-15
Where Can I Learn More Information About Essbase? ............................................................... 24-16

Part IX Reference Information

xiv
A Configuration File Settings
Configuration Files ................................................................................................................................. A-1
NQSConfig.INI File Configuration Settings..................................................................................... A-2
About Parameters in the NQSConfig.INI File .............................................................................. A-3
How to Update Parameters in NQSConfig.INI..................................................................... A-4
Repository Section Parameters........................................................................................................ A-4
Multitenancy Section Parameters ................................................................................................... A-5
MT_ROOT_DIRECTORY.......................................................................................................... A-5
MT_ENTRIES ............................................................................................................................. A-5
Query Result Cache Section Parameters........................................................................................ A-5
ENABLE ...................................................................................................................................... A-5
DATA_STORAGE_PATHS ...................................................................................................... A-5
MAX_ROWS_PER_CACHE_ENTRY ..................................................................................... A-7
MAX_CACHE_ENTRY_SIZE .................................................................................................. A-7
MAX_CACHE_ENTRIES.......................................................................................................... A-7
POPULATE_AGGREGATE_ROLLUP_HITS ........................................................................ A-7
USE_ADVANCED_HIT_DETECTION .................................................................................. A-8
MAX_SUBEXPR_SEARCH_DEPTH....................................................................................... A-9
DISABLE_SUBREQUEST_CACHING.................................................................................... A-9
CACHE_FILE_BUFFER_SIZE.................................................................................................. A-9
GLOBAL_CACHE_STORAGE_PATH ................................................................................... A-9
MAX_GLOBAL_CACHE_ENTRIES ..................................................................................... A-10
CACHE_POLL_SECONDS .................................................................................................... A-10
CLUSTER_AWARE_CACHE_LOGGING ........................................................................... A-10
General Section Parameters ........................................................................................................... A-10
LOCALE .................................................................................................................................... A-10
SORT_ORDER_LOCALE........................................................................................................ A-11
SORT_TYPE .............................................................................................................................. A-12
CASE_SENSITIVE_CHARACTER_COMPARISON .......................................................... A-13
NULL_VALUES_SORT_FIRST .............................................................................................. A-14
DATE_TIME_DISPLAY_FORMAT....................................................................................... A-14
DATE_DISPLAY_FORMAT................................................................................................... A-15
TIME_DISPLAY_FORMAT.................................................................................................... A-15
WORK_DIRECTORY_PATHS ............................................................................................... A-15
WORK_FILE_COMPRESSION_LEVEL .............................................................................. A-16
ENABLE_COLUMNAR_STORAGE_FOR_WORK_FILE.................................................. A-16
WORK_DIRECTORY_SIZE_GLOBAL_LIMIT ................................................................... A-16
MAX_WORK_FILE_SIZE_PERCENT .................................................................................. A-16
VIRTUAL_TABLE_PAGE_SIZE ............................................................................................ A-16
USE_LONG_MONTH_NAMES ............................................................................................ A-17
MEMORY_COMPACT_PERIOD_IN_SECONDS............................................................... A-17
USE_LONG_DAY_NAMES ................................................................................................... A-17
USE_UPPERCASE_MONTH_NAMES ................................................................................ A-17
USE_UPPERCASE_DAY_NAMES........................................................................................ A-17
UPPERCASE_USERNAME_FOR_INITBLOCK.................................................................. A-17
Security Section Parameters........................................................................................................... A-18
DEFAULT_PRIVILEGES ........................................................................................................ A-18

xv
PROJECT_INACCESSIBLE_COLUMN_AS_NULL ........................................................... A-18
IGNORE_LDAP_PWD_EXPIRY_WARNING..................................................................... A-18
MAX_AUTHENTICATION_TIME ....................................................................................... A-18
INIT_BLOCK_LOG_TIME_THRESHOLD........................................................................... A-19
NUM_INIT_BLOCK_THREADS_PER_USER ..................................................................... A-19
SSL.............................................................................................................................................. A-19
SSL_CERTIFICATE_FILE ....................................................................................................... A-19
SSL_PRIVATE_KEY_FILE ...................................................................................................... A-19
SSL_PK_PASSPHRASE_FILE ................................................................................................ A-19
SSL_PK_PASSPHRASE_PROGRAM.................................................................................... A-19
SSL_VERIFY_PEER.................................................................................................................. A-19
SSL_VERIFY_SERVERS .......................................................................................................... A-20
SSL_VERIFY_CLIENTS........................................................................................................... A-20
SSL_CA_CERTIFICATE_DIR................................................................................................. A-20
SSL_CA_CERTIFICATE_FILE ............................................................................................... A-20
SSL_TRUSTED_PEER_DNS ................................................................................................... A-20
SSL_INTERNAL_CA_CERTIFICATE_FILE ........................................................................ A-20
SSL_INTERNAL_TRUSTED_PEER_DNS ............................................................................ A-20
SSL_WEBSERVER_CA_CERTIFICATE_FILE ..................................................................... A-20
SSL_WEBSERVER_TRUSTED_PEER_DNS ......................................................................... A-20
SSL_CERT_VERIFICATION_DEPTH................................................................................... A-21
SSL_CIPHER_LIST .................................................................................................................. A-21
Server Section Parameters.............................................................................................................. A-21
READ_ONLY_MODE ............................................................................................................. A-21
MAX_SESSION_LIMIT ........................................................................................................... A-22
MAX_REQUEST_PER_SESSION_LIMIT ............................................................................. A-22
SERVER_THREAD_RANGE.................................................................................................. A-22
SERVER_THREAD_STACK_SIZE ........................................................................................ A-23
DB_GATEWAY_THREAD_RANGE .................................................................................... A-23
DB_GATEWAY_THREAD_STACK_SIZE ........................................................................... A-23
HTTP_CLIENT_THREAD_RANGE ..................................................................................... A-23
HTTP_CLIENT_THREAD_STACK_SIZE ............................................................................ A-23
MAX_EXPANDED_SUBQUERY_PREDICATES................................................................ A-24
MAX_QUERY_PLAN_CACHE_ENTRIES .......................................................................... A-24
MAX_QUERY_PLAN_CACHE_ENTRY_SIZE ................................................................... A-24
MAX_DRILLDOWN_INFO_CACHE_ENTRIES ................................................................ A-24
MAX_DRILLDOWN_QUERY_CACHE_ENTRIES ............................................................ A-25
INIT_BLOCK_CACHE_ENTRIES ......................................................................................... A-25
CLIENT_MGMT_THREADS_MAX...................................................................................... A-25
DEFAULT_JOBQUEUE_SIZE_PER_THREAD ................................................................... A-25
MAX_COLUMNS_IN_SELECT............................................................................................. A-25
MAX_LOGICAL_DIMENSION_TABLES............................................................................ A-25
MAX_LOGICAL_FACT_TABLES ........................................................................................ A-26
MAX_LOGICAL_MEASURES............................................................................................... A-26
MAX_SET_OPERATION_BLOCKS ..................................................................................... A-26
QUERY_LIMIT_WARNING_INSTEAD_OF_ERROR ....................................................... A-26
RPC_SERVICE_OR_PORT ..................................................................................................... A-27

xvi
LISTEN_ADDRESS.................................................................................................................. A-27
LISTEN_PORT.......................................................................................................................... A-27
ENABLE_DB_HINTS .............................................................................................................. A-27
PREVENT_DIVIDE_BY_ZERO.............................................................................................. A-27
CLUSTER_PARTICIPANT ..................................................................................................... A-28
REPOSITORY_PUBLISHING_DIRECTORY ....................................................................... A-28
REQUIRE_PUBLISHING_DIRECTORY .............................................................................. A-29
DISCONNECTED .................................................................................................................... A-29
AUTOMATIC_RESTART ....................................................................................................... A-29
VARIABLE_VALUE_LIMIT................................................................................................... A-29
EVALUATE_SUPPORT_LEVEL............................................................................................ A-29
FMW_SECURITY_SERVICE_URL........................................................................................ A-30
FMW_SECURITY_SERVICE_MAX_NUMBER_OF_CONNECTIONS ........................... A-30
FMW_SECURITY_SERVICE_MAX_NUMBER_OF_RETRIES ......................................... A-30
ENABLE_NUMERIC_DATA_TYPE ..................................................................................... A-30
ENDECA_SERVLET_URL...................................................................................................... A-31
High Availability Parameters........................................................................................................ A-31
HA_DB_PING_PERIOD_MILLISECS .................................................................................. A-31
Dynamic Library Section Parameters........................................................................................... A-31
Usage Tracking Section Parameters ............................................................................................. A-32
ENABLE .................................................................................................................................... A-33
DIRECT_INSERT ..................................................................................................................... A-33
STORAGE_DIRECTORY ........................................................................................................ A-34
CHECKPOINT_INTERVAL_MINUTES .............................................................................. A-34
FILE_ROLLOVER_INTERVAL_MINUTES ......................................................................... A-34
CODE_PAGE ............................................................................................................................ A-35
PHYSICAL_TABLE_NAME................................................................................................... A-35
CONNECTION_POOL ........................................................................................................... A-36
INIT_BLOCK_TABLE_NAME............................................................................................... A-36
INIT_BLOCK_CONNECTION_POOL ................................................................................. A-36
BUFFER_SIZE........................................................................................................................... A-36
BUFFER_TIME_LIMIT_SECONDS ....................................................................................... A-36
NUM_INSERT_THREADS..................................................................................................... A-37
MAX_INSERTS_PER_TRANSACTION ............................................................................... A-37
JOBQUEUE_SIZE_PER_INSERT_THREADPOOL_THREAD.......................................... A-37
THROW_INSERT_WHEN_JOBQUEUE_FULL .................................................................. A-37
SUMMARY_STATISTICS_LOGGING.................................................................................. A-37
SUMMARY_ADVISOR_TABLE_NAME ............................................................................. A-38
Query Optimization Flags Section Parameters........................................................................... A-38
STRONG_DATETIME_TYPE_CHECKING......................................................................... A-38
MDX Member Name Cache Section Parameters........................................................................ A-38
ENABLE .................................................................................................................................... A-38
DATA_STORAGE_PATH ...................................................................................................... A-38
MAX_SIZE_PER_USER........................................................................................................... A-39
MAX_MEMBER_PER_LEVEL ............................................................................................... A-39
MAX_CACHE_SIZE................................................................................................................ A-39
Aggregate Persistence Section Parameters.................................................................................. A-39

xvii
AGGREGATE_PREFIX ........................................................................................................... A-39
AGGREGATE_THREAD_POOL_SIZE ................................................................................ A-39
AGGREGATE_AW_NAME ................................................................................................... A-39
PREAGGREGATE_AW_CUBE.............................................................................................. A-39
SUPPORT_ANALYTICAL_WORKSPACE_TARGETS ..................................................... A-40
JavaHost Section Parameters......................................................................................................... A-40
JAVAHOST_HOSTNAME_OR_IP_ADDRESSES............................................................... A-40
JAVAHOST_HOSTNAME_OR_IP_ADDRESSES_OVERRIDE........................................ A-40
Datamart Automation Section Parameters.................................................................................. A-40
ESSBASE_SERVER................................................................................................................... A-40
DMA_DATABASE................................................................................................................... A-40

B Advanced Configuration Reference


Making Advanced Configuration Changes for Presentation Services......................................... B-1
Protecting Pages in Oracle BI EE from Attack .............................................................................. B-4
Using the JavaHost Service for Oracle BI Presentation Services................................................... B-5

C Mapping User Interface Labels with Configuration File Elements

D BI-Specific WLST Command Reference

xviii
Preface

The Oracle Business Intelligence Foundation Suite is a complete, open, and integrated
solution for all enterprise business intelligence needs, including reporting, ad hoc
queries, OLAP, dashboards, scorecards, and what-if analysis. The Oracle Business
Intelligence Foundation Suite includes Oracle Business Intelligence Enterprise Edition.
Oracle Business Intelligence Enterprise Edition (Oracle BI EE) is a comprehensive set
of enterprise business intelligence tools and infrastructure, including a scalable and
efficient query and analysis server, an ad-hoc query and analysis tool, interactive
dashboards, proactive intelligence and alerts, and an enterprise reporting engine.
The components of Oracle BI EE share a common service-oriented architecture, data
access services, analytic and calculation infrastructure, metadata management
services, semantic business model, security model and user preferences, and
administration tools. Oracle BI EE provides scalability and performance with
data-source specific optimized request generation, optimized data access, advanced
calculation, intelligent caching services, and clustering.
This guide contains information about system administration tasks and includes topics
on starting and stopping processes, managing logging and usage tracking, managing
query caching and performance, managing scalability and high availability, and
setting configuration options.

Audience
This document is intended for system administrators who are responsible for
managing Oracle Business Intelligence processes, logging, caching, monitoring, high
availability, and configuration.

Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle
Accessibility Program website at
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support


Oracle customers that have purchased support have access to electronic support
through My Oracle Support. For information, visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing
impaired.

xix
Related Documentation and Other Resources
See the Oracle Business Intelligence documentation library for a list of related Oracle
Business Intelligence documents.
In addition:
Go to the Oracle Learning Library for Oracle Business Intelligence-related online
training resources.
Go to the Product Information Center support note (Article ID 1267009.1) on My
Oracle Support at https://support.oracle.com.

Conventions
The following text conventions are used in this document:

Convention Meaning
boldface Boldface type indicates graphical user interface elements associated
with an action, or terms defined in text or the glossary.
italic Italic type indicates book titles, emphasis, or placeholder variables for
which you supply particular values.
monospace Monospace type indicates commands within a paragraph, URLs, code
in examples, text that appears on the screen, or text that you enter.

xx
New Features for Oracle Business Intelligence
System Administrators

This preface describes changes to system administration features for Oracle Business
Intelligence Enterprise Edition 12c (12.2.1).
If you are upgrading to Oracle BI EE from a previous release, then read the following
information carefully, because there are significant differences in features, tools, and
procedures. For more information about upgrading to Oracle BI EE 12c, see Oracle
Fusion Middleware Upgrade Guide for Oracle Business Intelligence.
This preface contains the following topics:
"New Features and Changes for Oracle BI EE 12c (12.2.1)"

New Features and Changes for Oracle BI EE 12c (12.2.1)


New system administration features and changes in Oracle BI EE 12c (12.2.1) include:
"Invoking WLST From a Single Location"
"Oracle Home Location Redefined and No Middleware Home"
"OPMN is No Longer Used in Fusion Middleware"
"Oracle Web Cache Not Part of Fusion Middleware"
"Moving From Test To Production is Carried Out in a Different Way"
"New Commands For Process Control"
"Managing Metadata In Business Intelligence Archive Files"
"Single Enterprise Install"
"Changes to Scaling Out"
"Simplified Configuration"
"Managing System Component Instances Using Commands"
"Collecting Diagnostic Bundles"

Invoking WLST From a Single Location


In previous releases, you invoked WLST from different locations, depending on
whether you were using the commands for Oracle WebLogic Server, system
components, or Java components such as Oracle SOA Suite. In this release, you invoke
WLST from:
(UNIX) ORACLE_HOME/oracle_common/common/bin/wlst.sh

xxi
(Windows) ORACLE_HOME\oracle_common\common\bin\wlst.cmd

For information, see Section 8.3.3, "Using the WebLogic Scripting Tool (WLST)".

Oracle Home Location Redefined and No Middleware Home


Redefining of the Oracle home and elimination of the Middleware home. See "New
And Deprecated Terminology for 12c" in Oracle Fusion Middleware Concepts.

OPMN is No Longer Used in Fusion Middleware


OPMN is no longer used in Oracle Fusion Middleware. Instead, system components
are managed by the WebLogic Management Framework, which includes WLST, Node
Manager and pack and unpack. See "What Is the WebLogic Management Framework"
in Oracle Fusion Middleware Concepts.

Oracle Web Cache Not Part of Fusion Middleware


Oracle Web Cache is no longer part of Oracle Fusion Middleware.

Moving From Test To Production is Carried Out in a Different Way


The test to production operation is still possible however, the process is different from
what was available in Oracle Business Intelligence Release 1 (11.1.1) as it applies solely
to metadata (content, data model and authorization). For information, see Chapter 22,
"Moving Oracle Business Intelligence Between Environments".

New Commands For Process Control


New process control commands replace the old start stop commands. For information,
see Section 1.5.3, "Process Control Commands".

Managing Metadata In Business Intelligence Archive Files


All Oracle Business Intelligence metadata, including repository, Presentation Services
catalog, and user authentication is stored in BAR archive files. The BAR file is a
mechanism for managing or moving a self contained set of Oracle BI metadata
between environments. For information, see Chapter 9, "Managing Metadata and
Working with Service Instances".

Single Enterprise Install


In this release the Oracle Universal installer offers a single install type for your
Enterprise which provides an Administration server, and a Managed server. For
information, see Section 1.3, "What Is the Oracle Business Intelligence System Logical
Architecture?" and Oracle Fusion Middleware Installation Guide for Oracle Business
Intelligence.

Changes to Scaling Out


In this release the scale out procedures for Oracle Business Intelligence have changed.
For information, see Chapter 3, "Scaling Your Deployment".

Simplified Configuration
Configuration files are no longer duplicated. Separate configuration files still exist for
example, for Oracle BI Presentation Services and BI Server, but they are not duplicated
in the case of a cluster. For information, see Section 8.3, "Configuring Oracle Business
Intelligence System Settings".

xxii
Managing System Component Instances Using Commands
OBIS (BI Server) system component instances are separately managed in BI 12.2.1
using service instance commands. For information, see Section 9.2, "Managing Service
Instances".

Collecting Diagnostic Bundles


A new script enables you to collect the diagnostic bundles needed by Oracle Support
or Development to help resolve issues. For information, see Section 6.2, "Collecting
Diagnostic Bundles".

Synchronizing Mid-Tier Database Connection Details Command


A new command enables you to synchronize mid-tier database connection details
when they have changed. For information, see " Synchronize Mid-Tier Database
Connection Details Command".

xxiii
xxiv
Part I
Part I Administering Oracle Business Intelligence

This part introduces administering the Oracle Business Intelligence system:


Chapter 1, "Introduction to Oracle Business Intelligence System Administration"
1
Introduction to Oracle Business Intelligence
1

System Administration

This chapter introduces system administration in Oracle Business Intelligence,


[2]

explains what a system administrator does; describes where to get started with typical
system administration tasks; describes the Oracle Business Intelligence architecture;
lists the tools that can help you complete system administration tasks, and provides
links to system requirements and certification information.
This chapter includes the following sections:
What Are the Oracle Business Intelligence System Administration Tasks?
Getting Started with Managing Oracle Business Intelligence
What Is the Oracle Business Intelligence System Logical Architecture?
Key Directories in Oracle Business Intelligence
What System Administration Tools Manage Oracle Business Intelligence?
Working with the Sample Application
Oracle BI Publisher Integration
Topics of Interest in Other Guides
System Requirements and Certification

1.1 What Are the Oracle Business Intelligence System Administration


Tasks?
Administering an Oracle Business Intelligence system involves the following tasks:
Configuring a system for deployment after installation
Configuring metadata and content, general preferences, and default system
settings.
Starting and stopping the system when required
Bringing the system up and down during system maintenance tasks.
Configuring security
Securing access to the Oracle Business Intelligence system, metadata, and data,
configuring Secure Sockets Layer (SSL) and Single Sign-On (SSO), and integration
with identity management systems.
Scaling out and configuring for high availability

Introduction to Oracle Business Intelligence System Administration 1-1


Getting Started with Managing Oracle Business Intelligence

Configuring the Oracle Business Intelligence system for linear scale-out


(increasing capacity with more components on a machine) and identifying and
removing single points of failure (adding more machines).
Managing performance and availability
Monitoring service levels and tuning performance.
Managing and resolving issues
Diagnosing errors and establishing resolutions.
Moving a system from test to production
Managing the steps for moving from a test to a production environment.
Backing up and recovering data
Preparing for and recovering from unexpected events.
For more information about these tasks, see Section 1.2, "Getting Started with
Managing Oracle Business Intelligence."

1.2 Getting Started with Managing Oracle Business Intelligence


Use this section to identify a task to complete, then click the corresponding link to
display the appropriate content.
Table 11 describes the typical system administration tasks that you perform in Oracle
Business Intelligence and indicates where to find related information.

Table 11 Oracle Business Intelligence System Administration Tasks


System Administration Task More Information
Learning about Oracle For more information, see the topics in this section.
Business Intelligence system
Contains information about the system architecture,
administration
components, tools, links to other related topics, and
certification information.
Viewing Oracle Business Section 8.2.2, "Displaying Oracle Business Intelligence Pages
Intelligence status in Fusion Middleware Control"
Also contains information about using Fusion Middleware
Control and using WebLogic Server Administration Console.
Configuring Oracle Business Section 8.3, "Configuring Oracle Business Intelligence
Intelligence System Settings"
Contains information about the available methods for
updating configuration settings and where configuration
files are located.
Starting and stopping Oracle Chapter 2, "Managing Oracle Business Intelligence
Business Intelligence Processes"
Contains various topics on starting and stopping
components, in addition to troubleshooting information.
Managing availability and Part III, "Scaling and Deploying for High Availability and
capacity Performance"
Contains chapters about scaling the environment, deploying
for high availability, performance tuning, and query caching.
Diagnosing problems and Part IV, "Resolving Issues"
resolving issues
Contains chapters about diagnosing and resolving issues
and about usage tracking.

1-2 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
What Is the Oracle Business Intelligence System Logical Architecture?

Table 11 (Cont.) Oracle Business Intelligence System Administration Tasks


System Administration Task More Information
Configuring Oracle Business Part V, "Configuring Oracle Business Intelligence"
Intelligence
Contains chapters about required configuration such as
configuring repositories and connections to external systems.
Modifying advanced Part VI, "Advanced Configuration Settings"
configuration settings
Contains chapters about advanced and optional
configuration settings for features such as analyses,
dashboards, and maps.
Configuring Oracle BI For more information, see Oracle Fusion Middleware
Scheduler Scheduling Jobs Guide for Oracle Business Intelligence Enterprise
Edition
Managing the life cycle. Part VII, "Managing the Life Cycle"
Contains chapters about life cycle management tasks such as
patching, moving between environments, and backup and
recovery.
Using Essbase with Oracle Part VIII, "Using Oracle Essbase With Oracle Business
Business Intelligence Intelligence"
Contains a chapter about using Essbase when it is installed
with Oracle Business Intelligence.
Securing the system Defines administrative role membership
Oracle Fusion Middleware Security Guide for Oracle
Business Intelligence Enterprise Edition
Secures middle-tier communications
Secure Sockets Layer (SSL) and Single Sign-On (SSO) are
not described in this guide. For information, see Oracle
Fusion Middleware Security Guide for Oracle Business
Intelligence Enterprise Edition.

1.3 What Is the Oracle Business Intelligence System Logical


Architecture?
The Oracle Business Intelligence system logical architecture comprises a single
integrated set of manageable components called the Oracle BI domain which can be
installed and configured to work together on a single host or can be clustered across
multiple hosts for performance and availability.

Note: You can improve the performance of your production system


by using a web server with Oracle Business Intelligence, such as
Oracle HTTP Server or Apache HTTP Server. A web server is not
included by default in the Oracle Business Intelligence installer and is
not part of the Oracle Business Intelligence system logical architecture.
You must install and configure a web server separately.

This section contains the following topics:


Section 1.3.1, "Oracle Business Intelligence System Architecture."
Section 1.3.2, "Oracle Business Intelligence Components."
Section 1.3.3, "About the Administration Server, Managed Servers, and System
Components."

Introduction to Oracle Business Intelligence System Administration 1-3


What Is the Oracle Business Intelligence System Logical Architecture?

1.3.1 Oracle Business Intelligence System Architecture


You install Oracle Business Intelligence on a single host, but can subsequently scale
out onto additional computers (see Chapter 3, "Scaling Your Deployment").
Figure 11 illustrates the Oracle Business Intelligence system architecture on a single
host. For more information, see Section 1.3.2, "Oracle Business Intelligence
Components".

Figure 11 Oracle Business Intelligence System Architecture

Oracle Business Intelligence is installed on a single host but can be scaled out onto
multiple hosts. Java components (WebLogic server domain) and system components
are clustered on each host as part of the single BI domain. The Administration Server
exists on both hosts, but will be active on only one host.

1.3.2 Oracle Business Intelligence Components


When you install Oracle Business Intelligence, you can install the following
components in the Oracle BI Domain on the host. The BI Domain consists of Java
components that are deployed into one or more Java EE (JEE) containers within a
single WebLogic server domain; system (non-JEE) components and processes; and
required configuration files, metadata repositories, and infrastructure.
Admin Server Deployed as a JEE container that runs in a dedicated Java virtual
machine that contains Java components for administering the system. These
components include Oracle WebLogic Server Administration Console, Oracle
Fusion Middleware Control, and JMX MBeans.
Managed Server Deployed as a JEE container that runs in a dedicated Java
virtual machine that provides the runtime environment for the Java-based services
and applications within the system. These services and applications include BI
Publisher and Visual Analyzer.
An Oracle BI domain contains one or more Managed Servers that are distributed
across one or more host computers.
Node Manager Provides process management services for the Administration
Server, Managed Server processes, and System Components.
For more information, see Oracle Fusion Middleware Node Manager Administrator's
Guide for Oracle WebLogic Server.

1-4 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
What Is the Oracle Business Intelligence System Logical Architecture?

System Components Deployed as server processes and provide the core


services that enable Oracle Business Intelligence.
For more information, see Section 1.3.3, "About the Administration Server,
Managed Servers, and System Components." For information about controlling
system processes, see Section 1.5.3, "Process Control Commands."
Other Domain Contents Includes all the necessary software, configuration
files, metadata, WLST commands, security, and connection and database
configuration information that are required to run an Oracle Business Intelligence
system.
For more information about:
Security configuration - See Oracle Fusion Middleware Security Guide for Oracle
Business Intelligence Enterprise Edition.
Metadata - See Chapter 9, "Managing Metadata and Working with Service
Instances" and Oracle Fusion Middleware Metadata Repository Builder's Guide for
Oracle Business Intelligence Enterprise Edition.

1.3.3 About the Administration Server, Managed Servers, and System Components
Oracle Business Intelligence contains an Administration server, Managed servers, and
system components which are described in the following sections:
Section 1.3.3.1, "About the Administration Server and Managed Servers"
Section 1.3.3.2, "About System Components"
For more information, see Oracle Fusion Middleware Administrator's Guide.
For information about Essbase when installed with Oracle Business Intelligence, see
Section 24.4, "Installing Essbase and Associated Components with Oracle Business
Intelligence".

1.3.3.1 About the Administration Server and Managed Servers


The Administration server and Managed servers are Java components deployed as one
or more Java EE applications and described in the following list:
Administration Server Manages configuration and runtime settings for Oracle
Business Intelligence for a single or multinode (distributed) BI domain, using:
Fusion Middleware Control An administrative user interface that is used
to manage the BI domain.
WebLogic Server Administration Console An administrative user interface
that provides advanced management for WebLogic, JEE components, and
security.
For more information, see "What System Administration Tools Manage Oracle
Business Intelligence?"
Managed Server Manages the following components:
Action Service This component provides the dedicated web services that
are required by the Action Framework and that enable an administrator to
manually configure which web service directories can be browsed by users
when they create actions.
Visual Analyzer This component provides a simple-to-use visual analytical
interface.

Introduction to Oracle Business Intelligence System Administration 1-5


Key Directories in Oracle Business Intelligence

BI Publisher This component provides an enterprise reporting solution for


authoring, managing, and delivering all types of highly formatted documents
to employees, customers, and suppliers.
Security This component provides dedicated web services that enable the
integration of the Oracle BI Server with the Oracle Fusion Middleware
security platform.
SOA Web Service This component provides dedicated web services for
objects in the Oracle BI Presentation Catalog, to invoke analyses, agents, and
conditions. These services make it easy to invoke Oracle Business Intelligence
functionality from Business Process Execution Language (BPEL) processes.
Presentation Services This component is a JEE application that routes
HTTP and SOAP requests to Oracle BI Presentation Services.

1.3.3.2 About System Components


System components are deployed as non-JEE components, such as processes and
services written in C++ and J2SE, and are described in the following list:
BI Server (OBIS) This component provides the query and data access
capabilities at the heart of Oracle Business Intelligence and provides services for
accessing and managing the enterprise semantic model (stored in a file with an
.RPD extension).
BI Scheduler (OBISCH) This component provides extensible scheduling for
analyses to be delivered to users at specified times. (Oracle BI Publisher has its
own scheduler.)
BI JavaHost (OBIJH) This component provides component services that enable
Oracle BI Presentation Services to support various components such as Java tasks
for Oracle BI Scheduler, Oracle BI Publisher, and graph generation. It also enables
Oracle BI Server query access to Hyperion Financial Management and Hyperion
Planning data sources.
Essbase This component provides support for Essbase.
BI Presentation Server (OBIPS) This component provides the framework and
interface for the presentation of business intelligence data to web clients. It
maintains an Oracle BI Presentation Catalog service on the file system for the
customization of this presentation framework.
Cluster Controller (OBICCS) This component distributes requests to the BI
Server, ensuring requests are evenly load-balanced across all BI Server process
instances in the BI domain.

1.4 Key Directories in Oracle Business Intelligence


There are three key top-level directories in Oracle Business Intelligence 12c:
ORACLE_HOME - for binaries.
There is one ORACLE_HOME for each host, or mounted from shared storage.
DOMAIN_HOME - for configuration, and logs.
There is one DOMAIN_HOME for each host (also referred to as BI_DOMAIN).
SDD (Singleton Data Directory) - for metadata and other cross-cluster files.
There is one SDD for each domain.

1-6 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
What System Administration Tools Manage Oracle Business Intelligence?

The SDD path (by default DOMAIN_HOME/bidata) is defined in the file


bi-environment.xml, located in:
DOMAIN_HOME/config/fmwconfig/bienv/core/bi-environment.xml

Note: If you have just created a domain on one host, then SDD is set
to DOMAIN_HOME/bidata.
If you have scaled-out, the SDD changes to use mounted shared
storage. In this case, the SDD will not be DOMAIN_HOME/bidata.

For more information, see Section 3.2.1, "Changing the Singleton Data Directory
(SDD)".

1.5 What System Administration Tools Manage Oracle Business


Intelligence?
This section describes system administration tools that are available to help you to
manage Oracle Business Intelligence. Table 12 outlines the tools and their purpose.

Table 12 System Administration Tools for Oracle Business Intelligence


Section Tool Purpose
Section 1.5.1 Fusion Middleware Control Monitor, manage, and configure system
components for Oracle Business
Intelligence.
Section 1.5.2 Oracle WebLogic Server Monitor and manage JEE Java components
Administration Console for Oracle Business Intelligence.
Section 1.5.3 Process control command line Manage system components for Oracle
tool Business Intelligence (for advanced users).
Section 1.5.4 Oracle WebLogic Scripting Programmatically administer Oracle
Tool (WLST) Business Intelligence.
Section 1.5.5 Oracle BI Administration Tool Manage the metadata repository for Oracle
Business Intelligence.
Section 1.5.6 Catalog Manager Manage the Oracle BI Presentation Catalog
online and offline.
Section 1.5.7 Job Manager Manage the Oracle BI Scheduler

1.5.1 Fusion Middleware Control


Fusion Middleware Control is a browser-based tool and the recommended method for
monitoring, managing, and configuring Oracle Business Intelligence components.
Fusion Middleware Control is used principally for managing the system components
of a BI domain and provides support for the following:
Starting, stopping, and restarting system components.
Configuring preferences and defaults.
Viewing status of scaled out components.
Managing performance and monitoring system metrics.
Performing diagnostics and logging.

Introduction to Oracle Business Intelligence System Administration 1-7


What System Administration Tools Manage Oracle Business Intelligence?

Fusion Middleware Control also provides access to Oracle WebLogic Server


Administration Console, where you monitor and manage Oracle Business Intelligence
Java components.
Fusion Middleware Control is available only if the Administration Server is running,
as described in Section 2.2, "Conditions for Starting the Oracle Business Intelligence
System."
For more information, see Chapter 8, "Using Tools for Managing and Configuring
Oracle Business Intelligence."

1.5.2 Oracle WebLogic Server Administration Console


Oracle WebLogic Server is a Java EE application server that supports the deployment
of Oracle Business Intelligence Java components in a robust, secure, highly available,
and scalable environment.
For more information, see Chapter 8, "Using Tools for Managing and Configuring
Oracle Business Intelligence."
Oracle WebLogic Server Administration Console enables you to monitor and manage a
WebLogic Server domain. Its capabilities include the following:
Monitoring the health and performance of JEE servers.
Configuring WebLogic server domains.
Stopping and starting JEE servers.
Viewing JEE server logs.
Managing user populations in the LDAP Server of the Oracle WebLogic Server
For more information, see Oracle Technology Network at the following location:
http://www.oracle.com/technetwork/index.html

1.5.3 Process Control Commands


Process control commands enable you to manage Oracle Business Intelligence system
components, support both local and distributed process management, and the
communication of process state (up, down, starting, and stopping).

Note: You also use Fusion Middleware Control user interface to


start, stop, and view status of system components.

Process control commands provide the following functionality to manage the Oracle
Business Intelligence system components:
A command-line interface for advanced users to control Oracle Fusion
Middleware components.
For information, see Section 2.3, "Using Commands to Stop, Start, and View Status
of Oracle Business Intelligence Processes."
An integrated way to manage Oracle Business Intelligence component processes.

1.5.4 Oracle WebLogic Scripting Tool (WLST)


The Oracle WebLogic Scripting Tool (WLST) is a command-line scripting environment
(for advanced administrator use), which enables you to programmatically administer

1-8 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Topics of Interest in Other Guides

Oracle Business Intelligence. The WLST scripting environment is based on the Java
scripting interpreter Jython. You can use this tool interactively on the command line, in
batch scripts that are supplied in a file (Script Mode, where scripts invoke a sequence
of WLST commands without requiring your input), or embedded in Java code. You
can extend the WebLogic scripting language by following the Jython language syntax.
For information, see Section 8.3.3, "Using the WebLogic Scripting Tool (WLST)", and
Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

1.5.5 Oracle BI Administration Tool


The Oracle BI Administration Tool enables you to manage the metadata repository. For
information, see Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle
Business Intelligence Enterprise Edition.

1.5.6 Catalog Manager


The Catalog Manager is a Windows tool that is the interface with the Oracle BI
Presentation Catalog. Through Catalog Manager, you can perform online and offline
management of Oracle BI Presentation Catalogs. For information, see Chapter 16,
"Configuring and Managing the Oracle BI Presentation Catalog".

1.5.7 Job Manager


The Job Manager is a Windows tool that is the interface with the Oracle BI Scheduler.
Through Job Manager, you can connect to, start and stop the Oracle BI Scheduler, add
and manage jobs, and manage job instances. For information, see Oracle Fusion
Middleware Scheduling Jobs Guide for Oracle Business Intelligence Enterprise Edition.

1.6 Working with the Sample Application


You can configure Oracle Business Intelligence with a simplified "Sample Application."
This application is often referred to as "SampleApp Lite."
You can also download and configure a more robust sample application. Instructions
for this configuration are available at the following location:
http://www.oracle.com/technetwork/middleware/bi-foundation/obiee-samples-1
67534.html
See "About the SampleApp Demonstration Repository" in Oracle Fusion Middleware
Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition for
information about the sample repository that is provided with Oracle Business
Intelligence.

1.7 Oracle BI Publisher Integration


This guide assumes that Oracle BI EE and BI Publisher have been installed and
configured to run as fully integrated components at your organization. If this is not the
case, then some mentions of BI Publisher in this guide might not be applicable to you.
For information about running BI Publisher, see Oracle Fusion Middleware User's Guide
for Oracle Business Intelligence Publisher.

1.8 Topics of Interest in Other Guides


Some topics that might be of interest to system administrators are covered in other
guides. Table 13 lists these topics and indicates where to go for more information.

Introduction to Oracle Business Intelligence System Administration 1-9


System Requirements and Certification

Table 13 Topics Covered in Other Guides


Topic Where to Go for More Information
Third-party tools and relational data Section 1.9, "System Requirements and Certification"
source adapters.
Configuration tasks for Oracle BI Oracle Fusion Middleware Scheduling Jobs Guide for
Scheduler. Oracle Business Intelligence Enterprise Edition
Configuring data sources. Oracle Fusion Middleware Metadata Repository Builder's
Guide for Oracle Business Intelligence Enterprise Edition
Security, including configuring SSO Oracle Fusion Middleware Security Guide for Oracle
and SSL. Business Intelligence Enterprise Edition
Installing and upgrading. Oracle Fusion Middleware Installation Guide for Oracle
Business Intelligence
Oracle Fusion Middleware Upgrade Guide for Oracle
Business Intelligence
Configuring comments and status Oracle Fusion Middleware Metadata Repository Builder's
overrides in Oracle Scorecard and Guide for Oracle Business Intelligence Enterprise Edition
Strategy Management.
Converting Oracle Business Oracle Fusion Middleware Metadata Repository Builder's
Intelligence proprietary metadata to Guide for Oracle Business Intelligence Enterprise Edition
an XML file and importing the
metadata into your Oracle database.
Propagating UI hints (labels and Oracle Fusion Middleware Metadata Repository Builder's
tooltips) from an ADF data source to Guide for Oracle Business Intelligence Enterprise Edition
display in Oracle BI Answers.

1.9 System Requirements and Certification


Refer to the system requirements and certification documentation for information
about hardware and software requirements, platforms, databases, and other
information. Both of these documents are available on Oracle Technology Network
(OTN).
The system requirements document covers information such as hardware and
software requirements, minimum disk space and memory requirements, and required
system libraries, packages, or patches:
http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-requirem
ents-100147.html
The certification document covers supported installation types, platforms, operating
systems, databases, JDKs, and third-party products:
http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certific
ation-100350.html

1-10 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Part II
Part II Managing Processes and Components

This part explains how to manage processes and components in Oracle Business
Intelligence. It includes the following chapter:
Chapter 2, "Managing Oracle Business Intelligence Processes"
2
Managing Oracle Business Intelligence
2

Processes

This chapter describes managing Oracle Business Intelligence processes and includes
[3]

the following sections:


About Managing Oracle Business Intelligence Processes
Conditions for Starting the Oracle Business Intelligence System
Using Commands to Stop, Start, and View Status of Oracle Business Intelligence
Processes
Using Fusion Middleware Control to Start and Stop BI System Component
Processes
Using Fusion Middleware Control to Start and Stop Java Components
Using Oracle WebLogic Server Administration Console to Start and Stop Java
Components

2.1 About Managing Oracle Business Intelligence Processes


System administrators start and stop the Oracle Business Intelligence system and
component processes to perform a range of maintenance operations that require
process downtime. Understanding the state (that is, up, down, starting, and stopping)
of each component in the Oracle Business Intelligence system is an essential activity
when diagnosing and resolving availability and performance issues, and when
performing life-cycle and management operations. For further information, see
Chapter 6, "Diagnosing and Resolving Issues in Oracle Business Intelligence".
Oracle Business Intelligence runs within Oracle WebLogic Server, and therefore Oracle
WebLogic Server must be started before Oracle Business Intelligence components can
be started and maintained.
To make changes to server configuration settings, the Oracle BI Presentation Catalog,
the repository (.rpd file offline), and other settings, you must restart the appropriate
Oracle Business Intelligence components before those changes can take effect.
When you stop Oracle Business Intelligence, end users are logged out, and when
ready, the system prompts you to log in again, ensuring session state consistency.

Note: For information about the Oracle Business Intelligence


installed components, see Section 1.3.2, "Oracle Business Intelligence
Components".

Managing Oracle Business Intelligence Processes 2-1


Conditions for Starting the Oracle Business Intelligence System

2.2 Conditions for Starting the Oracle Business Intelligence System


Starting the Oracle Business Intelligence system begins with the Administration
Server, then the Managed Servers, and the system components.
If the computer that hosts the Administration Server is not running or has been
rebooted, then you must ensure that the computer is running and you must start the
Oracle Business Intelligence system.
The following condition must be met to start the Oracle Business Intelligence system:
The repository database (which contains Scheduler schemas) that was specified
during installation must be running, and a network connection to it must be
available. Otherwise, error messages are displayed.
The procedure for starting the system differs slightly depending on the platform, as
described in the following sections.

2.3 Using Commands to Stop, Start, and View Status of Oracle Business
Intelligence Processes
You use script commands to stop, start, and view status of Oracle Business Intelligence
components.
Section 2.3.1, "Stopping Oracle Business Intelligence Component Processes in a
Domain"
Section 2.3.2, "Starting Oracle Business Intelligence Component Processes in a
Domain"
Section 2.3.3, "Viewing the Status of Oracle Business Intelligence Components in a
Domain"

2.3.1 Stopping Oracle Business Intelligence Component Processes in a Domain


This section describes how to stop running component processes within a domain.

Assumptions
The stop command does not stop remote Node Manager processes, unless you
specify r in the command.
The stop command runs only from the master host.
The stop command continues until all specified component processes are
shutdown.
The stop command initially prompts for credentials and automatically creates a
boot identity file, so that subsequent runs do not require credentials.
Stopping specific process may cause failover, so please familiarize yourself with
Chapter 3, "Scaling Your Deployment".

Pre-requisites
Node Manager must be running.
You must have file system permissions, and know the system administrator
identity credentials to boot WebLogic Server.
To stop component processes running in a domain using a command:
1. Enter an appropriate command to run the stop script located in:

2-2 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Using Commands to Stop, Start, and View Status of Oracle Business Intelligence Processes

DOMAIN_HOME/bitools/bin
On UNIX | Windows:
./stop.sh | stop.cmd {-i <list of instances>} {-r}
For example, ./stop.sh -i obis1,obips1

Table 21 Stop Component Processes Arguments


Argument Description
-r (optional) Stops the remote Node Managers.
-i <list of instances> (optional) Enables you to specify instances to shut
down in a comma-separated list. An instance can be
the administration server, a managed server or a
system component instance name.

If no instances are specified as arguments in the command, the administration


server, managed server and all system components are shutdown by default.
2. Component(s) are shut down.

2.3.2 Starting Oracle Business Intelligence Component Processes in a Domain


This section describes how to start all component processes within a domain.

Assumptions
The start command does not start remote Node Managers (on a clustered server),
but starts the local Node Manager if not already running.
The start command runs only from the master host.
The start command does not complete until component processes are either
started or fail consecutively to start three times.
Component processes start in order.
The command initially prompts for credentials and automatically creates a
boot.properties file, so that subsequent runs do not require credentials.

Pre-requisites
Remote Node Managers must be running.
You must have file system permissions, and know the boot identity credentials.
To start component processes running in a domain using a command:
1. Enter an appropriate command to run the start script located in:
DOMAIN_HOME/bitools/bin
On UNIX | Windows:
./start.sh | start.cmd {-noprompt} {-i <list of instances>} {-r}

For example, ./start.sh -i obis1,obips1

Table 22 Start Command Arguments


Argument Description
-r (optional) Starts the remote Node Managers.

Managing Oracle Business Intelligence Processes 2-3


Using Commands to Stop, Start, and View Status of Oracle Business Intelligence Processes

Table 22 (Cont.) Start Command Arguments


Argument Description
-i <list of instances> (optional) Enables you to specify instances to start up
in a comma-separated list. An instance can be the
administration server, a managed server or a system
component instance name.

If no instances are specified as arguments in the command, the administration


server, managed server, all system components, and local node manager are
started by default.
2. A list of the inactive components to be started is displayed.
3. Component(s) are started.
If you don't specify -i, then start will start all inactive processes. It does not fail if
something is already running.
The administration server, managed server(s), local node manager, and system
components are started.
The number of started components is displayed.
The status of all components is displayed.

2.3.3 Viewing the Status of Oracle Business Intelligence Components in a Domain


The status command displays a status report for components within a domain.

Assumptions
The status command reports node manager status.
The status command only runs from the Master Host.
The status command requires the local node manager process to be running.
The first run prompts you for credentials, and automatically creates a boot identity
file so that subsequent runs do not require credentials.

Pre-requisites
You must have file system permissions, and know the boot identity credentials.
To view the status of Oracle Business Intelligence components in a domain using a
command:
1. Enter an appropriate command to run the status script located in:
DOMAIN_HOME/bitools/bin
On UNIX | Windows:
./status.sh | status.cmd {-v}

where {-v} is verbose

2. The command displays component name, type, status, and machine name.

2-4 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Using Fusion Middleware Control to Start and Stop Java Components

2.4 Using Fusion Middleware Control to Start and Stop BI System


Component Processes
If the Oracle Business Intelligence system has been started, then you can start, stop,
and restart the Oracle Business Intelligence system component processes, using Fusion
Middleware Control.
If Fusion Middleware Control is not available, then see Section 2.3, "Using Commands
to Stop, Start, and View Status of Oracle Business Intelligence Processes."
To start and stop system component processes using Fusion Middleware Control:
1. Go to the Overview page, as described in Section 8.2.2, "Displaying Oracle
Business Intelligence Pages in Fusion Middleware Control".
2. Display the Processes tab of the Availability page, then either click Start All, or
Stop All, Restart All buttons for all processes, or select a process row and use the
appropriate button to start, stop, or restart an individual process as appropriate, as
shown in Figure 21.
You also use this page to view the status of system components.

Figure 21 Starting and Stopping System Component Processes

You can use other methods to start and stop Oracle Business Intelligence processes.
For more information, see:
Section 2.3, "Using Commands to Stop, Start, and View Status of Oracle Business
Intelligence Processes"
Section 2.6, "Using Oracle WebLogic Server Administration Console to Start and
Stop Java Components"

2.5 Using Fusion Middleware Control to Start and Stop Java Components
Use this topic to monitor status and start and stop Oracle Business Intelligence Java
components (Administration Server and Managed Servers) using Fusion Middleware
Control.

Managing Oracle Business Intelligence Processes 2-5


Using Fusion Middleware Control to Start and Stop Java Components

You can also display the WebLogic Server Administration Console to manage Java
components by choosing a menu option on the WebLogic Domain menu.
To monitor status and start and stop Java components using Fusion Middleware
Control:
1. Log in to Fusion Middleware Control.
For more information, see Section 8.2.1, "Logging into Fusion Middleware
Control."
2. Expand the WebLogic Domain folder and select the bi node.
Fusion Middleware Control displays the WebLogic Domain home page, as shown
in Figure 22.

Figure 22 The BI WebLogic Domain Home Page

The WebLogic Domain home page is the starting point for monitoring status of
servers, clusters, deployments, and partitions and for starting and stopping Oracle
Business Intelligence Java components using Fusion Middleware Control. You can
also click a menu option to display the WebLogic Server Administration Console,
where you can manage and configure Oracle Business Intelligence Java
components. For more information, see Section 8.4, "Managing Oracle Business
Intelligence Java Components Using the Oracle WebLogic Server Administration
Console."
3. Using the WebLogic Domain home page, you can perform the following Oracle
Business Intelligence management tasks:
View the status of Administration Server (AdminServer) and Managed Servers
(for example, bi_server1).
Start and stop selected Java components (for example, AdminServer or bi_
server1) using the WebLogic Domain menu Control option.
For information, see, Section 2.5, "Using Fusion Middleware Control to Start
and Stop Java Components."
Manage or configure the WebLogic server domain using the WebLogic Server
Administration Console by clicking a link on the WebLogic Domain menu.
For information about using WebLogic Server Administration Console, see
Section 8.4, "Managing Oracle Business Intelligence Java Components Using
the Oracle WebLogic Server Administration Console."

2-6 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Using Oracle WebLogic Server Administration Console to Start and Stop Java Components

2.6 Using Oracle WebLogic Server Administration Console to Start and


Stop Java Components
It is not recommended to use Oracle WebLogic Server Administration Console to start
and stop Java components. You can also use or Fusion Middleware Control to start
and stop Java components (see Section 2.4, "Using Fusion Middleware Control to Start
and Stop BI System Component Processes.").
To start and stop Java components using the Oracle WebLogic Server
Administration Console:
1. Start the Oracle WebLogic Server Administration Console.
For more information, see Section 8.4, "Managing Oracle Business Intelligence Java
Components Using the Oracle WebLogic Server Administration Console."
2. In the Domain Structure region, click Deployments.
3. The Oracle WebLogic Server Administration Console displays the Summary of
Deployments page.
4. Display the Control tab.
5. Select a check box for each component to start or stop.
6. Click Start or Stop to start or stop the selected components as required, as shown
in Figure 23.

Figure 23 Starting and Stopping in Administration Console

Managing Oracle Business Intelligence Processes 2-7


Using Oracle WebLogic Server Administration Console to Start and Stop Java Components

2-8 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Part III
Part III Scaling and Deploying for High Availability
and Performance

This part explains how to manage deployment, availability, and capacity for Oracle
Business Intelligence. It includes the following chapters:
Chapter 3, "Scaling Your Deployment"
Chapter 4, "Deploying Oracle Business Intelligence for High Availability"
Chapter 5, "Managing Performance Tuning and Query Caching"
3
Scaling Your Deployment
3

This chapter describes how to manage the capacity and availability of your
[4]

deployment of Oracle Business Intelligence. By default, Oracle Business Intelligence


system components are installed in a cluster configuration and are scalable. User web
requests can be directed to one of many Oracle BI Presentation Services components.
In turn, each Presentation Services component can take advantage of the availability of
multiple Oracle BI Servers.
You can expand or reduce the capacity of the system by adjusting the number of
processes available to the cluster. Increasing or decreasing the capacity of a system by
making effective use of resources is known as scalability. A scalable system can handle
increasing numbers of requests without adversely affecting response time and
throughput.
This chapter includes the following sections:
About Scaling Oracle Business Intelligence
Setting Up Shared Files and Directories
Managing Capacity in Oracle Business Intelligence (Vertically Scaling)
Managing Availability in Oracle Business Intelligence (Horizontally Scaling)
Validating That Your System Has Been Scaled Correctly

3.1 About Scaling Oracle Business Intelligence


Scaling is the process of increasing or decreasing the capacity of the system by
changing the number of processes available to service requests from Oracle Business
Intelligence clients. Scaling out a system provides additional capacity, while scaling in
a system reduces capacity. Scaling is also a critical part of configuring a deployment
for high availability. You can expand or reduce the capacity of the system by adjusting
the number of processes that are available to the cluster. A cluster consists of multiple
server instances that run simultaneously and work together to provide increased
scalability and reliability.
Scaling the Oracle Business Intelligence environment applies principally to
resource-intensive system processes and Java components. When you deploy more
processes, Oracle Business Intelligence can handle more requests while staying
responsive to requests.
Vertical scaling involves adding more Oracle Business Intelligence components to the
same computer, to make increased use of the hardware resources on that computer.
For example, Oracle Business Intelligence can be vertically scaled by increasing the
number of system components servicing requests on a given computer and results in
increased use of the hardware resources on a given computer.

Scaling Your Deployment 3-1


About Scaling Oracle Business Intelligence

Horizontal scaling involves adding more computers to the environment. For example,
Oracle Business Intelligence is horizontally scaled by distributing the processing of
requests across multiple computers.
You can scale both Oracle Business Intelligence Java components and system
components. See Section 1.3.3, "About the Administration Server, Managed Servers,
and System Components" for more information about these components.
The three system components that support both horizontal and vertical scale-out are
Oracle BI Presentation Services, the Oracle BI Server, and the JavaHost.
Oracle BI Scheduler uses Presentation Services and Oracle BI Server processes to
perform computationally intense work on its behalf, while the Cluster Controller only
manages other components and does not itself do any computationally intense work.
Because of this, there is no need to scale out either Oracle BI Scheduler or the Cluster
Controller. You can distribute these two processes as needed for high availability
deployments, but they do not need to be scaled for capacity.

3.1.1 How Do I Know When to Scale Out Processes?


Scale out system components and Managed Servers based on observed load. You can
use the performance metrics that are provided in Fusion Middleware Control to
monitor process state and to determine when you must increase capacity to improve
performance. For example, you might want to add a computer to the deployment
when CPU usage is over 50%, or when memory use is close to the system limit. See
Section 5.1, "Monitoring Service Levels" for more information about viewing system
metrics.
You also must scale out processes to achieve redundancy when you want to configure
a highly available Oracle Business Intelligence environment. See Section 4, "Deploying
Oracle Business Intelligence for High Availability" for more information.

3.1.2 What Processes Should I Scale?


Oracle Business Intelligence provides support for scale-out using a combination of the
Oracle Business Intelligence installer (for horizontal scale-out) and WebLogic Scripting
Tool (WLST) to scale system components both vertically and horizontally.
Follow these guidelines for scaling Managed Servers and system components:
Ensure that you run at least one Managed Server on each computer in the
deployment. During installation the Oracle Business Intelligence Configuration
Assistant provisions one Managed Server. Do not disable or remove it.
Do not remove individual Java components, because many perform essential
services for the system. Keep a full set of Java components on each Managed
Server. Any unused components likely do not have a significant performance
impact.
You can decide based on observed load which system components to run on each
computer. You can have 0 or more of each component type on a given computer in
the deployment. For example, you can have three Oracle BI Servers, two
JavaHosts, and four Presentation Services components. By default a symmetric set
of components is created on the scaled out computer.
You do not need to scale any configured HTTP servers along with either the
Managed Servers or system components. HTTP server configuration is
independent of the number of processes that you run.

3-2 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Setting Up Shared Files and Directories

3.2 Setting Up Shared Files and Directories


When you have multiple instances of a given Oracle Business Intelligence component,
files and directories including global cache and shared Oracle BI Scheduler scripts are
located on a shared storage device (such as NAS or SAN). This simplifies management
of your system (see Figure 31) including scale out of Oracle Business Intelligence
components.

Figure 31 Scaling Out and Shared Storage

This section contains the following topics:


Section 3.2.1, "Changing the Singleton Data Directory (SDD)"
Section 3.2.2, "Setting Up the Global Cache"

3.2.1 Changing the Singleton Data Directory (SDD)


Oracle Business Intelligence metadata is stored in a singleton data directory (SDD), the
default location is set to:
DOMAIN_HOME/bidata
The SDD path is defined in the file bi-environment.xml, located in:
DOMAIN_HOME/config/fmwconfig/bienv/core/bi-environment.xml
For more information, see Section 1.4, "Key Directories in Oracle Business
Intelligence".

To change the singleton data directory (SDD):


1. Create a shared directory and make sure it is available on all hosts.

For example, on Windows:


dir \\example.com\dir
For example, on UNIX:
ls /oraclehome/user_projects/domains/bi/bidata

Scaling Your Deployment 3-3


Managing Capacity in Oracle Business Intelligence (Vertically Scaling)

2. Stop all Oracle Business Intelligence processes by running the following command
located in:
DOMAIN_HOME/bitools/bin
For example on UNIX enter:
./stop.sh

3. Backup the file bi-environment.xml, and existing SDD if desired.


4. Open the file bi-environment.xml for editing, and specify the singleton path.
For example:
<bi:singleton-data-directory>/oraclehome/user_
projects/domains/bi/bidata/</bi:singleton-data-directory>

5. Save the file.


6. Copy the contents of the bidata directory to the shared directory previously
created.
7. Start all Oracle Business Intelligence processes by running the following command
located in:
DOMAIN_HOME/bitools/bin/
For example on UNIX enter:
./start.sh

The SDD is now configured for all host computers.

3.2.2 Setting Up the Global Cache


The global cache is a query cache that is shared by all Oracle BI Servers participating
in a cluster. For more information, see Section 5.4.6, "About the Global Cache."
It is recommended that you configure the global cache so that cache seeding and
purging events can be shared by all Oracle BI Servers participating in a cluster.
To set up the global cache:
1. Use the Performance tab of the Capacity Management page in Fusion Middleware
Control to set the Global cache path and Global cache size options.
For more information, see Section 5.5.4, "Using Fusion Middleware Control to Set
Global Cache Parameters".

3.3 Managing Capacity in Oracle Business Intelligence (Vertically


Scaling)
You can change the number of Oracle Business Intelligence system components and
managed servers to suit capacity requirements.
You should first configure shared files and directories for clustered components to use
(for information, see Section 3.2, "Setting Up Shared Files and Directories").
You can change the number of BI System components to suit capacity requirements.
The commands described in this section should only be used by advanced users.
Section 3.3.1, "Adding System Components"

3-4 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Managing Capacity in Oracle Business Intelligence (Vertically Scaling)

Section 3.3.2, "Removing System Components"

3.3.1 Adding System Components


You can add BI System Components to a computer when the system is stopped
(offline).
Assumptions:
You must have appropriate file system permissions.
Ports are allocated from the Oracle Business Intelligence port range, unless
otherwise specified.
Supported system component types are OBIPS (BI Presentation Server), OBICCS
(Cluster Controller), OBIJH (BI JavaHost), and OBISCH (BI Scheduler).
OBIS is not scaled out because OBIS instances are managed as part of service
instances.
For more information, see Section 1.3.3.2, "About System Components".
You can only create two instances each of the component types OBICCS, OBISCH
(one active, one passive). Therefore, if it is required to add another instance on
another host, then an existing instance must first be removed.
To add system components:
1. Create a system component using an appropriate WLST command from:
ORACLE_HOME/oracle_common/common/bin/wlst.sh
Use the following syntax to create an Oracle BI Presentation Server component:
createOBIPSComponent(domainHome, machine)
Where machine is the WebLogic logical computer name (for example 'm1'). Use
WLST or the WebLogic Admin Console (if running) to discover the logical
machine name.
For example to create a new Presentation Services system component on UNIX,
enter:
createOBIPSComponent("/oraclehome/user_projects/domains/bi", "m1")

All commands take a DOMAIN_HOME a machine name and an optional port


specification

Table 31 Create BI Component Commands


Command Description
createOBICCSComponent(domainHome, This command creates a new cluster
machine, port=None, portMonitor=None) component.
createOBISCHComponent(domainHome, This command creates a new scheduler
machine, port=None, component.
portMonitor=None,portScript=None)
createOBIPSComponent(domainHome, This command creates a new BI Presentation
machine, port=None) Server component.
createOBIJHComponent(domainHome, This command creates a new JavaHost
machine, port=None) component
listBISystemComponents(domainHome) This command lists all of the system
components in the domain.

Scaling Your Deployment 3-5


Managing Capacity in Oracle Business Intelligence (Vertically Scaling)

Table 31 (Cont.) Create BI Component Commands


Command Description
getBISystemComponents(domainHome, This command displays details of system
instanceId) component with specified instanceID.

The newly created system component instance name (or component details) is
displayed.
2. Start the new component in:
DOMAIN_HOME/bitools/bin/
For example, enter:
./start.sh

For information, see Section 2.3.2, "Starting Oracle Business Intelligence


Component Processes in a Domain".
Post Conditions
The new component is created.
New port(s) are allocated.
The new component is started.
For more information, Section 8.3.3, "Using the WebLogic Scripting Tool (WLST)".

3.3.2 Removing System Components


You can remove an unwanted or inactive Oracle Business Intelligence system
component instances from a computer.
Assumptions:
Run commands when system is stopped (offline), as long as you have appropriate
file system (offline) privileges.
Supported system component types are OBIPS (BI Presentation Server), OBICCS
(BI Cluster Controller), OBIJH (BI JavaHost), and OBISCH (BI Scheduler). For
information, see Section 1.3.3.2, "About System Components".
To remove a system component:
1. Stop the system using the stop script located in:
DOMAIN_HOME/bitools/bin/
For example on UNIX enter:
./stop.sh

For more information, see Section 2.3.1, "Stopping Oracle Business Intelligence
Component Processes in a Domain".
2. Delete a system component by running the deleteBISystemComponent WLST
command from ORACLE_HOME/oracle_common/common/bin/wlst.sh:
deleteBISystemComponent(domainHome, instanceId)
Where domainHome is the DOMAIN_HOME for the domain, and instanceID is
the BI component ID (for example, obips1, obis4)
For example:

3-6 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Managing Availability in Oracle Business Intelligence (Horizontally Scaling)

deleteBISystemComponent("/oraclehome/user_projects/domains/bi", "obips1")

This removes system component(s) and un-allocates ports.


For more information, Section 8.3.3, "Using the WebLogic Scripting Tool (WLST)".
3. The deleted system component name is displayed.
4. Start the system by running the following command located in:
DOMAIN_HOME/bitools/bin/
For example on UNIX enter:
./start.sh

For more information, see Section 2.3.2, "Starting Oracle Business Intelligence
Component Processes in a Domain".

3.4 Managing Availability in Oracle Business Intelligence (Horizontally


Scaling)
If you have multiple instances of a given Oracle Business Intelligence component in
the deployment, you should first configure shared files and directories for the
clustered components to use (for information, see Section 3.2, "Setting Up Shared Files
and Directories").
After horizontally scaling out, you typically configure an HTTP server and load
balancer to distribute requests across multiple managed servers. For information, see
"Load Balancing in a Cluster" in Oracle Fusion Middleware Using Clusters for Oracle
WebLogic Server. If a front end load balancer has been setup, then you must set the
WebLogic Server Front-End Host and Port for the BI cluster (bi_cluster).
The commands described in this section should only be used by advanced users. Note
that availability commands automatically create a symmetric set of processes when
configuring additional hosts.
For more information, Section 8.3.3, "Using the WebLogic Scripting Tool (WLST)".

Note: To add a new node to a cluster when SSL has been configured,
you must scale out to the new cluster (see Section 3.4.1, "Adding New
Computers"), then ensure SSL is correctly set up (see "Configuring SSL
in Oracle Business Intelligence" in Oracle Fusion Middleware Security
Guide for Oracle Business Intelligence Enterprise Edition).

Section 3.4.1, "Adding New Computers"


Section 3.4.2, "Removing Existing Computers"

3.4.1 Adding New Computers


You can add a new computer to extend the BI cluster across multiple computers,
increasing availability and capacity.
Assumptions
The new computer must meet the same install pre-requisites (for example,
operating system, memory).
SDD must have been set up.

Scaling Your Deployment 3-7


Managing Availability in Oracle Business Intelligence (Horizontally Scaling)

ORACLE_HOME must be the same absolute path on both computers.


It is recommended, but not required, that the DOMAIN_HOME is the same on
both hosts.
A symmetric set of active-active components is created on the new computer.
The BI system must be stopped (offline).
You must have appropriate file system (offline) or Weblogic Administrator (online)
permissions.
The same ports are allocated as on the original host.
The managed server is added to the existing Oracle Business Intelligence cluster.
Cluster Controller, Scheduler and BI Server mastership is not changed.
Note that optional base computer and server parameters are provided to support
the case where m1/bi_server1 has been deleted.
Unless provided the computer (WebLogic machine) name will default to the listen
address and must be less than 32 characters.
To add a new computer:
Creates an additional managed server, node manager, system components and
services on the new computer.
1. On the master computer, run the clone script:
DOMAIN_HOME/bitools/bin/clone_bi_machine.sh|cmd [-m <new machine
name>] <listen address> <pack file>
<new machine name> is optional and defaults to the listen address.
The SSL certificate step is done for you in the script.
2. On the new machine, install WebLogic Server and Oracle Business Intelligence.
For information, see Oracle Fusion Middleware Installation Guide for Oracle Business
Intelligence.
3. Test connectivity between the two hosts.
4. Copy the pack file from the master host computer (the one with the Admin server)
to the new computer.
5. On the new computer, apply the pack file by running the unpack command.
For example in:
ORACLE_HOME/oracle_common/common/bin
./unpack.sh domain=DOMAIN_HOME -nodemanager_
type=PerDomainNodeManager
6. Re-synchronize the data source on new machine.
Run the script in:
DOMAIN_HOME/bitools/bin/sync_midtier_db.cmd
For more information, see Table D3, " Synchronize Mid-Tier Database Connection
Details Command".
7. On the new computer, start node manager using the startNodeManager script.
For example in:

3-8 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Managing Availability in Oracle Business Intelligence (Horizontally Scaling)

/oraclehome/user_projects/domains/bi/bin

Enter:
./startNodeManager.sh

8. On the master host computer, start inactive components in:


DOMAIN_HOME/bitools/bin/
Enter:
./start.sh

For information, see Section 2.3.2, "Starting Oracle Business Intelligence


Component Processes in a Domain".
Post Conditions
Computer, Managed server, Node Manager and System Components are created.
Service instances are registered on the second computer.
Ports are allocated.

3.4.2 Removing Existing Computers


Remove a failed or redundant computer from a BI Cluster.
Assumptions
No binaries, configuration or state is deleted from the removed computer.
Cluster Controller, Scheduler and BI Server mastership is unchanged.
You cannot remove the master computer.
Service Instance registrations can be added or removed.
The BI system can be running (online) or stopped (offline).
You must have appropriate file system (offline) or Weblogic Administrator (online)
permissions.
The command does not result in a loss of service.
The command can only result in a loss of availability if forced by the user.
Pre-requisites
If possible, you should stop active components on the target computer before
removing it using the status.sh and stop.sh scripts. For information, see Section 2.3,
"Using Commands to Stop, Start, and View Status of Oracle Business Intelligence
Processes".
To remove an existing computer:
1. Use the deleteBIMachine WLST command to remove components created by
cloneBIMachine or clone_bi_machine.sh in:
ORACLE_HOME/oracle_common/common/bin/wlst.sh
For example:
deleteBIMachine(DOMAIN_HOME, <machine>)
Or run the delete_bi_machine.sh script in:
DOMAIN_HOME/bitools/bin/delete_bi_machine.sh|cmd machineName

Scaling Your Deployment 3-9


Validating That Your System Has Been Scaled Correctly

2. The command displays the removed computer name.


Post Conditions
Computer, Managed Server, Node Manager and System Components are removed
from that computer.
Service Instances are unregistered from that computer.
Ports are unallocated.

3.5 Validating That Your System Has Been Scaled Correctly


You can use Fusion Middleware Control and the Oracle WebLogic Server
Administration Console, and the command line to verify the status of the scaled-out
components.
This section contains the following topics:
Section 3.5.1, "Using Fusion Middleware Control to View System Component
Availability"
Section 3.5.2, "Using the Administration Console to View Managed Server
Availability"
For information about using a command to see the status, see Section 2.3.3, "Viewing
the Status of Oracle Business Intelligence Components in a Domain".

3.5.1 Using Fusion Middleware Control to View System Component Availability


You can use Fusion Middleware Control to view the status of all system components
in your deployment.
To view status for system components:
1. Go to the Business Intelligence Overview page, as described in Section 8.2.2,
"Displaying Oracle Business Intelligence Pages in Fusion Middleware Control."
2. Display the Processes tab of the Availability page.
On this page, you can:
View the status of all configured system components
View the host, and port of each system component running
Start, stop, or restart all processes
Start, stop, or restart selected system components
Click the 'Help for This Page' Help menu option to access page-level help.
Figure 32 shows the Processes tab of the Availability page.

3-10 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Validating That Your System Has Been Scaled Correctly

Figure 32 Processes Tab of Availability Page in Fusion Middleware Control

3.5.2 Using the Administration Console to View Managed Server Availability


You can use the Administration Console to view the status of all Managed Servers in
your deployment.
To view status for Managed Servers:
1. Log in to the Oracle WebLogic Server Administration Console.
2. Select Environment, then select Servers to go to the Summary of Servers page. On
this page, you can see any Managed Servers that were added on new hosts in your
deployment.
Figure 33 shows the Summary of Servers page.

Scaling Your Deployment 3-11


Validating That Your System Has Been Scaled Correctly

Figure 33 Summary of Servers Page in Oracle WebLogic Server Administration


Console

3-12 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
4
Deploying Oracle Business Intelligence for
4

High Availability

This chapter describes how to configure Oracle Business Intelligence components for
[5]

high availability. It also describes the functionality available in Fusion Middleware


Control to manage system availability, and provides information about using the
Cluster Manager in the Administration Tool.
This chapter does not provide information about setting up additional high
availability configuration for other components in the stack, including database tier,
web tier, Administration Server, and identity management availability. For more
information about these topics and how they relate to Oracle Business Intelligence
deployments, see the following documents:
"Configuring High Availability for Oracle Business Intelligence and EPM" in
Oracle Fusion Middleware High Availability Guide explains how to implement high
availability across the stack, including how to configure a fault tolerant HTTP load
balancer and a highly available database for the Oracle Business Intelligence
schemas
Oracle Fusion Middleware Enterprise Deployment Guide for Oracle Business Intelligence
explains how to deploy Oracle Business Intelligence based on an architectural
blueprint that follows Oracle recommended best practices for security and high
availability, including web tier, database tier, Administration Server, and identity
management availability
This chapter includes the following sections:
About Oracle Business Intelligence Components in a Clustered Environment
Configuring Oracle Business Intelligence Components for High Availability
Optional Configuration for Oracle Business Intelligence High Availability
Using the Cluster Manager
Troubleshooting an Oracle Business Intelligence Clustered Environment

4.1 About Oracle Business Intelligence Components in a Clustered


Environment
Figure 41 shows the system components and Java components in a highly available
Oracle Business Intelligence deployment. See Section 1.3.3, "About the Administration
Server, Managed Servers, and System Components" for more information about
system components and Java components.

Deploying Oracle Business Intelligence for High Availability 4-1


About Oracle Business Intelligence Components in a Clustered Environment

Figure 41 A Highly Available Oracle Business Intelligence Deployment

In Figure 41, the Oracle Business Intelligence Java components are deployed on the
BI_SERVER1 and BI_SERVER2 Managed Servers on APPHOST1 and APPHOST2.
These Managed Servers are configured in an Oracle WebLogic cluster.
Oracle BI Presentation Services, JavaHost, Oracle BI Cluster Controller, Oracle BI
Scheduler, and Oracle BI Server are system components installed on APPHOST1 and
APPHOST2 and configured as a cluster. The Cluster Controller and Oracle BI
Scheduler on APPHOST2 are passive (they are started but do not service requests) and
are only made active if APPHOST1 components fail.
Customer metadata is stored in the shared SDD (as BAR files for import or export).

4.1.1 Recommendations for Availability


In a production system, it is recommended that you deploy two or more instances of
every component on two or more computers, so that each component type has an
instance running on more than one computer for fault tolerance. This configuration
provides redundancy for Managed Servers and system components, an essential

4-2 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
About Oracle Business Intelligence Components in a Clustered Environment

requirement for high availability and failover. You can see whether the system has any
single points of failure by using the Failover tab of the Availability page in Fusion
Middleware Control. See Section 4.1.2, "Using Fusion Middleware Control to Identify
Single Points of Failure" for more information.
You can also ensure high availability by configuring redundancy in the database tier
(Oracle RAC recommended), web tier, and for the Administration Server. See
"Configuring High Availability for Oracle Business Intelligence and EPM" in Oracle
Fusion Middleware High Availability Guide for more information.
Note also the following requirements:
All Oracle BI Servers participating in the cluster must be within the same domain
and on the same LAN subnet. Geographically separated computers are not
supported.
The clock on each server participating in a cluster must be kept in synchronization.
Out-of-sync clocks can skew reporting.

4.1.2 Using Fusion Middleware Control to Identify Single Points of Failure


Before you begin this procedure, ensure that you are familiar with the information in
Section 8.3.1, "Using Fusion Middleware Control".
To identify single points of failure:
1. Go to the Business Intelligence Overview page, as described in Section 8.2.2,
"Displaying Oracle Business Intelligence Pages in Fusion Middleware Control."
2. Display the Failover tab of the Availability page.
On this page, you can view scaled out system components and whether to
configure primary/secondary system components.
Click the 'Help for this page' help menu option to access the page-level help for its
elements.

4.1.3 Achieving High Availability Using an Active-Passive Model


As an alternative to setting up the active-active configuration described in the
previous sections, you can set up Oracle Business Intelligence in an active-passive
configuration using Oracle Fusion Middleware Cold Failover Cluster (Cold Failover
Cluster). In a Cold Failover Cluster configuration, two or more application server
instances are configured to serve the same application workload, but only one is active
at any particular time.
A two-node Cold Failover Cluster can be used to achieve active-passive availability for
Oracle Business Intelligence. In a Cold Failover Cluster, one node is active while the
other is passive, on standby. In the event that the active node fails, the standby node is
activated, and Oracle Business Intelligence continues servicing clients from that node.
All Oracle Business Intelligence components are failed over to the new active node. No
Oracle Business Intelligence components run on the failed node after the failover.
See "Active-Passive Topologies for Oracle Fusion Middleware High Availability" in
Oracle Fusion Middleware High Availability Guide for detailed information.

Deploying Oracle Business Intelligence for High Availability 4-3


Configuring Oracle Business Intelligence Components for High Availability

4.2 Configuring Oracle Business Intelligence Components for High


Availability
To configure Oracle Business Intelligence for high availability, you must ensure that
the system has no single points of failure by scaling out the Oracle BI Server,
Presentation Services, and the JavaHost so that you have at least two of each
component type, distributed across at least two computers.
Table 41 lists the tasks that you must perform to configure high availability for Oracle
Business Intelligence.

Table 41 Task Summary for Configuring High Availability


Task Where to Go for More Information
Horizontally scale out the Oracle Business Section 3.4, "Managing Availability in
Intelligence deployment so that it includes two Oracle Business Intelligence
computers with a full set of Java and system (Horizontally Scaling)"
components on each host. This task includes running
the Oracle Business Intelligence installer, and
configuration assistant, and scaling out system
components.
Verify that the new components are available. Section 3.5.1, "Using Fusion
Middleware Control to View System
Component Availability"

4.3 Optional Configuration for Oracle Business Intelligence High


Availability
Follow the steps in this section to perform optional configuration for Oracle Business
Intelligence high availability.
This section contains the following topics:
Section 4.3.1, "Setting Optional Cluster Controller Parameters"
Section 4.3.2, "Setting Optional Presentation Services Parameters"
Section 4.3.3, "Setting Optional Oracle BI Presentation Services Plug-in
Parameters"

4.3.1 Setting Optional Cluster Controller Parameters


You can set optional parameters that are related to Cluster Controller heartbeat
frequency in the bi_cluster_config.xml file.
To set optional parameters in the ClusterConfig.xml file:
1. Open the bi_cluster_config.xml file for editing at:
BI_DOMAIN/config/fmwconfig/biconfig/OBICCS
2. Table 42 describes default values for the cluster communication parameters
under the ClusterProperties element. Optionally, modify the parameter values as
required for the deployment.

4-4 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Optional Configuration for Oracle Business Intelligence High Availability

Table 42 bi_cluster_config.xml Parameters for Cluster Communication


Parameter Description Default Value
ServerPollSeconds The frequency in seconds of heartbeat 5
messages between the Cluster Controller
and the Oracle BI Server and Oracle BI
Scheduler nodes in the cluster.
ControllerPollSeconds The frequency in seconds of heartbeat 5
messages between the Cluster Controllers.

3. Save and close the file.


4. Restart Oracle Business Intelligence.
Example 41 shows example parameters in the bi_cluster_config.xml file. Note that
any additional elements that are not shown in this example are centrally managed and
cannot be set manually.

Example 41 Sample Parameters for Clustering in bi_cluster_config.xml


<bi:ClusterProperties>
<bi:ClusterEnabled>true</bi:ClusterEnabled>
<bi:ServerPollSeconds>5</bi:ServerPollSeconds>
<bi:ControllerPollSeconds>5</bi:ControllerPollSeconds>
</bi:ClusterProperties>

4.3.2 Setting Optional Presentation Services Parameters


You can optionally configure certain parameters that control the communication
between Presentation Services and the JavaHost component. To configure Presentation
Services, set parameters in the instanceconfig.xml file on each computer that hosts
Presentation Services.
To configure Presentation Services for clustering:
1. Open the configuration file instanceconfig.xml for editing at:
BI_DOMAIN/config/fmwconfig/biconfig/OBIPS
2. Under the ServerInstance tag, the JavaHostProxy element has optional
subelements. Table 43 describes these optional subelements.

Table 43 Optional Subelements for the JavaHostProxy Element


Subelement Attribute Description
LoadBalancer/Ping keepAliveMaxFailures Specifies the number of ping failures
required before the host is declared
nonfunctioning. The default value is 5.
LoadBalancer/Ping keepAliveFrequencySecs Specifies the ping frequency in seconds.
The default value is 20.

3. Save and close the file.


4. Restart Oracle Business Intelligence.

4.3.3 Setting Optional Oracle BI Presentation Services Plug-in Parameters


You can optionally configure the Oracle BI Presentation Services Plug-in to control
session redirection behavior.

Deploying Oracle Business Intelligence for High Availability 4-5


Using the Cluster Manager

To set optional parameters for the Oracle BI Presentation Services Plug-in:


1. Open the bridgeconfig.properties file for editing, for example at:
BI_DOMAIN/config/fmwconfig/biconfig/bridgconfig.properties
2. Optionally, you can include the parameter AlwaysKeepSessionAffiliation to
control whether requests that belong to the same session can be redirected to
another Presentation Services component if the current Presentation Services
component score is too low.
The instance score is an internal score that the load balancing algorithm associates
with each Presentation Services instance in the cluster. It is based on various
metrics that are collected by the load balancer.
Set this parameter to true to disallow request redirection, or false to allow requests
to be redirected. For example:
oracle.bi.presentation.sawconnect.loadbalance.AlwaysKeepSessionAffiliation=tru
e

3. Save and close the file.


4. Restart the analytics application from the Oracle WebLogic Server Administration
Console. If Oracle BI Publisher is using the Oracle BI Presentation Catalog, then
the xmlpserver application must also be restarted.

4.4 Using the Cluster Manager


The Cluster Manager in the Administration Tool was used in previous releases to
monitor and manage Oracle BI Server, Oracle BI Scheduler, and Cluster Controller
instances. This tool is still supported in the current release.
Although you use Fusion Middleware Control for most administrative tasks that relate
to clustered components, the Cluster Manager provides a useful way to view the state
of clustered components. For example, you can view the currently active Oracle BI
Scheduler instance and see which Oracle BI Server is the Master BI Server. Fusion
Middleware Control shows the current status of clustered components, but does not
provide a way to view the current state.
The Cluster Manager lets you monitor, analyze, and manage the operations of Oracle
BI Server, Oracle BI Scheduler, and Cluster Controller instances in a cluster. It provides
status, cache, and session information. The Cluster Manager is available only when the
Administration Tool is connected to a clustered DSN.
If all Cluster Controllers or Oracle BI Servers in the cluster are currently stopped or
offline, then you cannot access the Cluster Manager to start them. You must manually
start one Cluster Controller (generally, the primary) and one Oracle BI Server.
The Cluster Manager window has two panes: the Explorer pane on the left side and
the Information pane on the right side. The Explorer pane displays hierarchical
information about the servers, schedulers, and controllers that comprise a cluster. The
Information pane shows detailed information about an item selected in the Explorer
pane.
The Cluster Manager window refreshes every minute by default. You can change the
interval.
To set the refresh interval for the display:
1. In the Administration Tool, open a repository in online mode.
2. Select Manage, then Clusters.

4-6 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Using the Cluster Manager

3. Select Refresh, then Every, and select another value from the list.
4. To refresh the display at any time, ensure that the Cluster Manager is the active
window and press F5, or select Refresh, then Now. This action retrieves the most
current information for the cluster.

4.4.1 Viewing and Managing Cluster Information


The section describes how to view status, cache, and session information about a
cluster and the meaning of the information provided.

4.4.1.1 Status Information


The Status view is automatically displayed when you first open the Cluster Manager
window. You can also access the Status view by selecting View, then Status in the
Cluster Manager window.
The categories of information that are displayed in the Information pane might vary
depending on the server to which the Administration Tool is connected. Table 44
describes categories that might appear.

Table 44 Status Columns


Column Description
Last The time that the Cluster Controller or Oracle BI Server communicated with the
Reported Controlling Cluster Controller. If the server or controller is offline, then this field
Time might be blank.
Name The name of the computer that is hosting the Oracle BI Server or Cluster
Controller.
Role The role of the object in the cluster:
Controlling. A Cluster Controller that is currently assigned the responsibility
for control of the cluster.
Primary. The Primary Cluster Controller. This role is not displayed if the
Primary Cluster Controller is currently the controlling Cluster Controller.
Secondary. The Secondary Cluster Controller. This role is not displayed if the
Secondary Cluster Controller is currently the controlling Cluster Controller.
Clustered server. An Oracle BI Server that is a member of the cluster. This
role is not displayed for the clustered server that is defined as the master
server.
Master. The clustered server that the Administration Tool connects to for
editing repositories in online mode.
Active. The Oracle BI Scheduler is active.
Sessions This field is available when either Servers or an individual server is selected in the
Explorer pane. It shows the number of sessions that are currently logged on to a
clustered server.
Start Time The timestamp showing when the Cluster Controller or Oracle BI Server was last
started. This field is blank if the Cluster Controller or clustered server is offline.

Deploying Oracle Business Intelligence for High Availability 4-7


Using the Cluster Manager

Table 44 (Cont.) Status Columns


Column Description
Status The status of the object in the cluster:
Online. The Cluster Controller or Oracle BI Server is online. Online Cluster
Controllers can accept session requests and assign them to available servers
within the cluster. Online Oracle BI Servers can be assigned sessions by the
Cluster Controller.
Quiesce. This status is applicable to clustered servers only. When a server is
quiesced, any activity in progress on outstanding sessions can complete
before the server transitions to Offline status.
Offline. The Cluster Controller or Oracle BI Server is offline. Offline Cluster
Controllers cannot accept session requests or assign sessions to available
servers within the cluster. Offline Oracle BI Servers do not communicate with
the controlling Cluster Controller and cannot accept sessions assigned by the
controlling Cluster Controller. If the server subsequently becomes available,
then the server can participate in the cluster. To stop the Cluster Controller or
clustered server after quiescing it, enter the Stop command.
Forced Offline. This status applies to clustered servers only. The Oracle BI
Server has been stopped. This is identical to the offline status, except that if
the Oracle BI Server comes back online, it is not assigned requests. The server
remains in this state until the Start command is issued against this server
from the Administration Tool Cluster Manager, or both Cluster Controllers
are shut down and restarted.
Online: Active. The Oracle BI Scheduler instance is online, running, and the
one to which Oracle BI Scheduler clients connect. This instance executes jobs.
Online: Inactive. The Oracle BI Scheduler is online but not running. This
instance is ready to take over for the active instance if the active instance
becomes unavailable.
Online: Inactive Pending. The Oracle BI Scheduler was active and is trying
to go into an inactive state. This might take a few minutes (for example, if
multiple jobs are running).
Type When Clusters is selected in the Explorer pane, this field is available. There are
three types:
Controller. The object is a Cluster Controller.
Server. The object is an Oracle BI Server.
Scheduler. The object is a Scheduler Server.

4.4.1.2 Cache Information


The Cache view is available in the Cluster Manager window if caching is enabled.
The categories of information and their display sequence are controlled by the Options
settings. Table 45 describes categories that might appear.

Table 45 Cache View Columns


Column Description
Business Model Name of the business model that is associated with the cache entry.
Column count Number of columns in each row of this cache entry's result set.
Created Time the result set of the cache entry was created.
Creation elapsed Time, in milliseconds, needed to create the result set for this cache entry.
time
Full size Full size is the maximum size used, considering variable length columns,
compression algorithm, and other factors. The actual size of the result set is
smaller than Full size.

4-8 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Using the Cluster Manager

Table 45 (Cont.) Cache View Columns


Column Description
Last used Last time the result set of the cache entry satisfied a query. (After an
unexpected shutdown of an Oracle BI Server, the Last used time might
temporarily have a stale value, that is, older than the true value.)
Row count Number of rows that are generated by the query.
Row size Size of each row (in bytes) in this cache entry's result set.
SQL Text of the SQL statement that generated the cache entry.
Use count Number of times that this cache entry's result set has satisfied a query
(since Oracle BI Server startup).
User Name of the user who submitted the query that resulted in the cache entry.

To view cache information:


1. Click an individual server in the Explorer pane, and then select View, then Cache.

4.4.1.3 Session Information


The Session view is available for Oracle BI Servers. The information is arranged in two
windows, described in Table 46.
Session window: Appears on the top. Shows users currently logged on to the
Oracle BI Server.
Request window: Appears on the bottom. Shows active query requests for the
user selected in the Session window.
Table 46 describes the information that is displayed in the Session window.

Table 46 Session Window Columns (Top Window)


Column Description
Catalog Name of the Oracle BI Presentation Catalog to which the session is connected.
Client Type Type of client session. The client type of Administration is reserved for the
user who is logged in with the Oracle BI Administrator user ID.
Last Active Timestamp of the last activity on the session or the query.
Time
Logon Time Timestamp when the session logged on to the Oracle BI Server.
Repository Logical name of the repository to which the session is connected.
Session ID Unique internal identifier that the Oracle BI Server assigns each session when
the session is initiated.
User Name of the user connected.

Table 47 describes the information that is displayed in the Request window.

Table 47 Request Window Columns (Bottom Window)


Column Description
Last Active Time Timestamp of the last activity on the session or the query.
Request ID Unique internal identifier that the Oracle BI Server assigns each query
when the query is initiated.

Deploying Oracle Business Intelligence for High Availability 4-9


Using the Cluster Manager

Table 47 (Cont.) Request Window Columns (Bottom Window)


Column Description
Session ID Unique internal identifier that the Oracle BI Server assigns each session
when the session is initiated.
Start Time Time of the initial query request.
Status These are the possible values. Due to the speed at which some processes
complete, not all values for any given request or session might appear.
Idle. There is presently no activity on the request or session.
Fetching. The request is being retrieved.
Fetched. The request has been retrieved.
Preparing. The request is being prepared for processing.
Prepared. The request has been prepared for processing and is ready
for execution.
Executing. The request is currently running. To terminate a request,
select it and click Kill Request. The user receives an informational
message that indicates that the Oracle BI Administrator canceled the
request.
Executed. The request has finished running.
Succeeded. The request ran to completion successfully.
Canceled. The request has been canceled.
Failed. An error was encountered during the processing or running
of the request.

To view session information:


1. Select a server in the Explorer pane, and select View, then Sessions.
Session information for the server is displayed in the Information pane. It shows
all users logged into the server and all current query requests for each user.
To disconnect a session:
1. In the Session view, right-click the session in the Session window (top window)
and click Disconnect.
When you disconnect a session, the ODBC session is terminated. Client users who
were connected over this session receives errors if they attempt to run queries.
Users must log out, then log back in again to start a new session.
To terminate a query request:
1. In the Session view, right-click the request in the Request window (bottom
window) and click Kill Request.
When you terminate a query request, the user who is initiating the query receives
an error.

4.4.1.4 Server Information


Selecting Server info from the View menu provides information about the cluster
server, such as server version number.

4-10 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Troubleshooting an Oracle Business Intelligence Clustered Environment

4.5 Troubleshooting an Oracle Business Intelligence Clustered


Environment
Use Fusion Middleware Control and the Administration Console to check the status of
system processes. See Section 3.5.1, "Using Fusion Middleware Control to View System
Component Availability" and Section 3.5.2, "Using the Administration Console to View
Managed Server Availability" for more information.
After enabling clustering, load balancing, and failover capabilities, you can
troubleshoot issues that might occur in the deployment using the following:
Messages and errors that are reported in Fusion Middleware Control
Log files for Oracle Business Intelligence components, also available through
Fusion Middleware Control
Review the log files for every Oracle Business Intelligence system component in the
cluster. Log files record any client-side failures that might occur due to an incorrect
configuration. Although some failover events are not logged, the Cluster Controller
log file records crashes of any Oracle BI Scheduler or Oracle BI Server component. You
can also review the Event Viewer log on Windows and the syslog on Linux or UNIX.
See Chapter 6, "Diagnosing and Resolving Issues in Oracle Business Intelligence" for
more information about log files.

4.5.1 Avoiding Errors with Network Appliance Devices When the Oracle BI Server Is
Running on Linux or UNIX
The following information applies to deployments with Oracle BI Server components
on Linux or UNIX platforms that access Oracle Business Intelligence shared files and
directories on a NAS device from Network Appliance. For environments with Oracle
BI Server components on Linux or UNIX that use the NTFS security style, the
recommended Network Appliance Data ONTAP storage operating system version is
6.3.1 or later.
Linux or UNIX computers saving to an NTFS qtree in Data ONTAP versions 6.0.3
through 6.3 might see permission errors when trying to save designs. Use the
following Data ONTAP setting to silently ignore attempts to set UNIX permissions on
NTFS qtrees after the design file is saved:
options cifs.ntfs_ignore_unix_security_ops on

Deploying Oracle Business Intelligence for High Availability 4-11


Troubleshooting an Oracle Business Intelligence Clustered Environment

4-12 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
5
Managing Performance Tuning and Query
5

Caching

This chapter describes ways to improve Oracle Business Intelligence query


[6]

performance, including a performance tuning overview and information about


monitoring system metrics. It also describes how to manage and use the query cache, a
feature that enables the Oracle BI Server to save the results of a query in cache files
and then reuse those results later when a similar query is requested. Using cache, the
cost of database processing must be paid only once for a query, not every time the
query is run.
See also the following Oracle Fusion Middleware resources on performance tuning for
your system:
Oracle Fusion Middleware Performance and Tuning Guide
Oracle Fusion Middleware Performance and Tuning for Oracle WebLogic Server
This chapter includes the following sections:
Monitoring Service Levels
About Query Performance Tuning
Setting Performance Parameters in Fusion Middleware Control
About the Oracle BI Server Query Cache
Configuring Query Caching
Monitoring and Managing the Cache
Strategies for Using the Cache
Cache Event Processing with an Event Polling Table
Managing the Oracle BI Presentation Services Cache Settings
Improving Oracle BI Web Client Performance
Setting the JVM Heap Size for Oracle Business Intelligence
Capturing Metrics Using the Dynamic Monitoring Service

5.1 Monitoring Service Levels


Understanding service levels typically involves monitoring process state and viewing
system metrics.

Managing Performance Tuning and Query Caching 5-1


Monitoring Service Levels

Oracle Business Intelligence automatically and continuously measures runtime


performance in real time. The performance metrics are automatically enabled; you do
not need to set options or perform any extra configuration to collect them.
System metrics are available in Fusion Middleware Control for system components
within a given Oracle Business Intelligence installation. If you encounter a problem,
such as an application that is running slowly or is hanging, then you can view more
detailed performance information to learn more information about the problem.
You can use WSLT commands to periodically save metric information to a file so that
you have a record of past metric values. See "DMS Custom WLST Commands" in
Oracle Fusion Middleware WebLogic Scripting Tool Command Reference for more
information.
You can also view metrics for Java components using the Oracle WebLogic Server
Administration Console.
This section contains the following topics:
Section 5.1.1, "Using Fusion Middleware Control to View All Oracle Business
Intelligence Metrics"
Section 5.1.2, "Using the Administration Console to View Metrics for Java
Components"

5.1.1 Using Fusion Middleware Control to View All Oracle Business Intelligence Metrics
You can view and graph all the available Oracle Business Intelligence metrics from the
Performance Summary page in Fusion Middleware Control. The data is logged
transiently (that is, logging starts when you go to the page and select a particular
metric for display).
To use Fusion Middleware Control to view all performance metrics for Oracle
Business Intelligence:
1. In the tree navigator, expand the Business Intelligence folder and right-click the
biinstance node.
2. Select Monitoring, then select Performance Summary. The Performance
Summary page appears, displaying a selection of metrics for this Oracle Business
Intelligence installation.
3. To customize the metrics that are displayed on the Performance Summary page,
click Show Metric Palette. Then, expand the appropriate metric category and
select or deselect individual metrics. The metrics that you select are displayed on
the Performance Summary page.
For information about a particular metric, right-click the metric and select Help.

5.1.2 Using the Administration Console to View Metrics for Java Components
Use the Administration Console to view metrics for Java components. You can view
metrics on the Monitoring tab for the selected Managed Server, or you can use the
Metric Browser. If your deployment is based on the Simple Install type, use the
Monitoring tab for the Administration Server.
To view metrics for Oracle Business Intelligence in the Monitoring tab:
1. Log in to the Administration Console.
2. Expand the Environment node in the Domain Structure window.
3. Click Servers. The Summary of Servers page is displayed.

5-2 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
About Query Performance Tuning

4. Click the server name (for example, oracle_bi1 or AdminServer(admin)).


5. Click the Monitoring tab.
Click Help for more information about the metrics displayed on this tab.
To access the Administration Console Metric Browser:
1. Log in to the Administration Console.
2. Click Monitoring Dashboard under Charts and Graphs.
3. Click the Metric Browser tab.
Click Help for more information about using the Metric Browser.

5.2 About Query Performance Tuning


This section describes some important considerations for improving query
performance with the Oracle BI Server.
The following list summarizes methods that you can use to improve query
performance:
Tuning and indexing underlying databases: For Oracle BI Server database
queries to return quickly, the underlying databases must be configured, tuned, and
indexed correctly. Note that different database products have different tuning
considerations.
If there are queries that return slowly from the underlying databases, then you can
capture the SQL statements for the queries in the query log and provide them to
the database administrator (DBA) for analysis. See Section 6.5, "Managing the
Query Log" for more information about configuring query logging on the system.
Aggregate tables: It is extremely important to use aggregate tables to improve
query performance. Aggregate tables contain precalculated summarizations of
data. It is much faster to retrieve an answer from an aggregate table than to
recompute the answer from thousands of rows of detail.
The Oracle BI Server uses aggregate tables automatically, if they have been
properly specified in the repository. See Oracle Fusion Middleware Metadata
Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition for
examples of setting up aggregate navigation.
Query caching: The Oracle BI Server can store query results for reuse by
subsequent queries. Query caching can dramatically improve the apparent
performance of the system for users, particularly for commonly used dashboards,
but it does not improve performance for most ad-hoc analysis.
See Section 5.4, "About the Oracle BI Server Query Cache" for more information
about query caching concepts and setup.
Setting parameters in Fusion Middleware Control: You can set various
performance configuration parameters using Fusion Middleware Control to
improve system performance. See Section 5.3, "Setting Performance Parameters in
Fusion Middleware Control" for more information.
Setting parameters in NQSConfig.INI: The NQSConfig.INI file contains
additional configuration and tuning parameters for the Oracle BI Server, including
parameters to configure disk space for temporary storage, set virtual table page
sizes, and several other advanced configuration settings. See Appendix A,
"Configuration File Settings" for more information.

Managing Performance Tuning and Query Caching 5-3


Setting Performance Parameters in Fusion Middleware Control

You can also improve the overall performance of the system by increasing throughput
by scaling out system components. See Chapter 3, "Scaling Your Deployment" for more
information.

5.3 Setting Performance Parameters in Fusion Middleware Control


This section describes performance options that you can set in Fusion Middleware
Control.
This section contains the following topics:
Section 5.3.1, "Using Fusion Middleware Control to Disallow RPD Updates"
Section 5.3.2, "Using Fusion Middleware Control to Set the User Session Log-Off
Period"
Section 5.3.3, "Using Fusion Middleware Control to Set Configuration Options for
Data in Tables and Pivot Tables"
Section 5.3.4, "Using Fusion Middleware Control to Set the Maximum Number of
Rows Processed to Render a Table"

5.3.1 Using Fusion Middleware Control to Disallow RPD Updates


You can use Fusion Middleware Control to allow or prevent updates to the default
repository file. Setting this parameter affects whether you can update the repository
when the Administration Tool connects in both online and offline mode. It also affects
whether you can perform other repository update operations using other utilities, such
as biserverxmlcli. Note that the aggregate persistence feature is not available when
repository updates are prevented.
Preventing repository updates can improve Oracle BI Server performance, because in
this mode, the Oracle BI Server does not need to handle lock control.
If you choose to prevent repository updates, then when the Administration Tool opens
a repository in either online or offline mode, a message informs the user that the
repository is read-only.
Before you begin this procedure, ensure that you are familiar with the information in
Section 8.3.1, "Using Fusion Middleware Control".
To use Fusion Middleware Control to prevent repository updates:
1. Go to the Business Intelligence Overview page, as described in Section 8.2.2,
"Displaying Oracle Business Intelligence Pages in Fusion Middleware Control."
2. Display the Performance tab of the Configuration page.
3. Click Lock and Edit to enable changes to be made.
4. Select Disallow RPD Updates to prevent updates to the repository file.
Click the 'Help for this page' menu option to access the page-level help.
5. Click Apply, then click Activate Changes.
6. Return to the Business Intelligence Overview page and click Restart.
For information about corresponding configuration file elements, see Table C1,
" Performance Tab - Mapping Between User Interface Labels and Configuration File
Elements".

5-4 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Setting Performance Parameters in Fusion Middleware Control

5.3.2 Using Fusion Middleware Control to Set the User Session Log-Off Period
You can override the time to elapse, in minutes, before a user is automatically logged
off. Before you begin this procedure, ensure that you are familiar with the information
in Section 8.3.1, "Using Fusion Middleware Control".
To use Fusion Middleware Control to set the client session log-off period:
1. Go to the Business Intelligence Overview page, as described in Section 8.2.2,
"Displaying Oracle Business Intelligence Pages in Fusion Middleware Control."
2. Display the Performance tab of the Configuration page.
3. Click Lock and Edit to enable changes to be made.
4. Complete the User Session Expiry option using the description in the help topic
for the page.
Click the 'Help for this page' menu option to access the page-level help.
5. Click Apply, then click Activate Changes to execute your changes and release the
lock to enable another system administrator to make changes.
6. Return to the Business Intelligence Overview page and click Restart.
For information about corresponding configuration file elements, see Table C1,
" Performance Tab - Mapping Between User Interface Labels and Configuration File
Elements".

5.3.3 Using Fusion Middleware Control to Set Configuration Options for Data in Tables
and Pivot Tables
Advanced configuration settings are described in Section 17.3, "Configuring for
Displaying and Processing Data in Views."
Before you begin this procedure, ensure that you are familiar with the information in
Section 8.3.1, "Using Fusion Middleware Control".
To use Fusion Middleware Control to set configuration options for views:
1. Go to the Business Intelligence Overview page, as described in Section 8.2.2,
"Displaying Oracle Business Intelligence Pages in Fusion Middleware Control."
2. Display the Performance tab of the Configuration page.
3. Click Lock and Edit to enable changes to be made.
4. Complete the elements using the descriptions in the help topic for the page.
Click the 'Help for this page' menu option to access the page-level help for the
following options:
Maximum Number of Rows to Download option
Maximum Number of Rows Per Page to Include option

Note: In general, the 'Maximum Number of Rows to Download'


option and the 'Maximum Number of Rows Processed when
Rendering a Table View' option discussed in Section 5.3.4, "Using
Fusion Middleware Control to Set the Maximum Number of Rows
Processed to Render a Table" should be set to the same values to avoid
getting 'Exceeded configured maximum number of allowed input
records' errors.

Managing Performance Tuning and Query Caching 5-5


Setting Performance Parameters in Fusion Middleware Control

5. Click Apply, then click Activate Changes.


6. Return to the Business Intelligence Overview page and click Restart.
For information about corresponding configuration file elements, see Table C1,
" Performance Tab - Mapping Between User Interface Labels and Configuration File
Elements".

5.3.4 Using Fusion Middleware Control to Set the Maximum Number of Rows
Processed to Render a Table
You can override the maximum number of rows that can be fetched and processed
from the Oracle BI Server for rendering a table. Reducing the number of rows in a
table can significantly improve performance by reducing the system resources that can
be consumed by a given user session.
Advanced configuration settings are described in Section 17.3, "Configuring for
Displaying and Processing Data in Views."
Note the following when setting this value:
This specification applies to tables, not to pivot tables.
The default value is 65000. The minimum value is 50. If the user exceeds the
maximum value, then the server returns an error message when the table view is
rendered. The maximum value is at least 16 bits, which varies by platform. The
system is likely to consume all its memory before approaching a number larger
than this value.
Before you begin this procedure, ensure that you are familiar with the information in
Section 8.3.1, "Using Fusion Middleware Control".
To use Fusion Middleware Control to set the maximum number of rows that are
processed to render a table:
1. Go to the Business Intelligence Overview page, as described in Section 8.2.2,
"Displaying Oracle Business Intelligence Pages in Fusion Middleware Control."
2. Display the Performance tab of the Configuration page.
3. Click Lock and Edit to enable changes to be made.
4. Complete the Maximum Number of Rows Processed to Render A Table View
option using the description in the help topic for the page. Enter an integer value
greater than 50.
Click the 'Help for this page' menu option to access the page-level help for the box.

Note: In general, the 'Maximum Number of Rows Processed when


Rendering a Table View' option and the 'Maximum Number of Rows
to Download' option discussed in Section 5.3.3, "Using Fusion
Middleware Control to Set Configuration Options for Data in Tables
and Pivot Tables" should be set to the same values to avoid getting
'Exceeded configured maximum number of allowed input records'
errors.

5. Click Apply, then click Activate Changes.


6. Return to the Business Intelligence Overview page and click Restart.

5-6 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
About the Oracle BI Server Query Cache

For information about corresponding configuration file elements, see Table C1,
" Performance Tab - Mapping Between User Interface Labels and Configuration File
Elements".

5.4 About the Oracle BI Server Query Cache


You can configure the Oracle BI Server to maintain a local, disk-based cache of query
result sets (query cache). The query cache enables the Oracle BI Server to satisfy many
subsequent query requests without accessing back-end data sources, thereby
increasing query performance.
As updates occur on the back-end databases, the query cache entries can become stale.
Therefore, you must periodically remove entries from the query cache using one of the
following methods:
Manually. In the Oracle BI Administration Tool, in the Manage menu, select
Cache to open the Cache Manager. The Cache Manager provides the most
flexibility in choosing which cache entries to purge and when to purge them, but it
requires manual intervention. See Section 5.7.4, "Using the Cache Manager" for
more information.
Automatically. In the Administration Tool, you can disable cache for the system,
set caching attributes for a specific physical table, and use Oracle Business
Intelligence event tables to purge cache automatically. See Section 5.6, "Monitoring
and Managing the Cache" for additional information.
Programmatically. The Oracle BI Server provides ODBC-extension functions for
purging cache entries programmatically. These functions give you the choice and
the timing flexibility of the Cache Manager with the automation of event tables.
You can write your own scripts to call these functions at times that fit your needs.
See Section 5.6.2, "Purging and Maintaining Cache Using ODBC Procedures" for
more information.
The parameters that control query caching are located in Fusion Middleware Control
and in the NQSConfig.INI file, described in Appendix A, "Configuration File Settings."
See also Section 5.7.3, "Using Agents to Seed the Oracle BI Server Cache" for additional
information.
This section contains the following topics:
Section 5.4.1, "Query Cache Architecture"
Section 5.4.2, "Advantages of Caching"
Section 5.4.3, "Costs of Caching"
Section 5.4.4, "Cache Sharing Across Users"
Section 5.4.5, "About the Refresh Interval for XML Data Sources"
Section 5.4.6, "About the Global Cache"

5.4.1 Query Cache Architecture


The query cache consists of cache storage space, cache metadata, and cache detection
in query compilation.
The process of the Oracle BI Server accessing the cache metadata is very fast. If the
metadata shows a cache hit, then the bulk of the query processing is eliminated, and
the results are immediately returned to the user. The process of adding the new results
to the cache is independent of the results being returned to the user; the only effect on

Managing Performance Tuning and Query Caching 5-7


About the Oracle BI Server Query Cache

the running query is the resources that are consumed in the process of writing the
cached results.
Query cache entries are portable across different operating systems, such as Windows
or UNIX 64-bit architectures. Incompatible cache entries are automatically removed.
Note that query cache entries are not portable across different releases of Oracle
Business Intelligence, such as between Version 10.1.3.2 and 11.1.1.
Caching occurs by default at the subrequest level, which results in multiple cache
entries for some SQL statements. Caching subrequests improves performance and the
cache hit ratio, especially for queries that combine real-time and historical data. To
disable subrequest caching, set the NQSConfig.INI file parameter DISABLE_
SUBREQUEST_CACHING to YES. See Appendix A, "Configuration File Settings" for more
information.

5.4.2 Advantages of Caching


The fastest way to process a query is to skip the bulk of the processing and use a
precomputed answer. With query caching, the Oracle BI Server stores the
precomputed results of queries in a local cache. If another query can use those results,
then all database processing for that query is eliminated. This can result in dramatic
improvements in the average query response time.
In addition to improving performance, being able to answer a query from a local cache
conserves network resources and processing time on the database server. Network
resources are conserved because the intermediate results do not have to come over the
network to the Oracle BI Server. Not running the query on the database frees the
database server to do other work. If the database uses a charge back system, then it
could save money in the budget as well.
Another benefit of using the cache to answer a query is savings in processing time on
the Oracle BI Server, especially if the query results are retrieved from multiple
databases. Depending on the query, there might be considerable join and sort
processing in the server. If the query is already calculated, then this processing is
avoided, freeing server resources for other tasks.
To summarize, query caching has the following advantages:
Dramatic improvement of query performance
Less network traffic
Reduction in database processing
Reduction in Oracle BI Server processing overhead

5.4.3 Costs of Caching


Query caching has many obvious benefits, but also certain costs:
Disk space for the cache
Administrative costs of managing the cache
Potential for cached results being stale
CPU and disk I/O on server computer
With cache management, the benefits typically far outweigh the costs.
The following sections discuss the costs of caching.

5-8 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
About the Oracle BI Server Query Cache

5.4.3.1 Disk Space


The query cache requires dedicated disk space. How much space depends on the
query volume, the size of the query result sets, and how much disk space that you
choose to allocate to the cache. For performance purposes, use a disk exclusively for
caching, and ensure that it is a high performance, high reliability type of disk system.

5.4.3.2 Administrative Tasks


Some administrative tasks are associated with caching. You must set the cache
persistence time for each physical table appropriately, knowing how often data in that
table is updated. When the frequency of the update varies, you must keep track of
when changes occur and purge the cache manually when necessary. You can also
create a cache event polling table and modify applications to update the polling table
when changes to the databases occur, making the system event-driven.
The Oracle BI Server also provides ODBC-extension functions for purging cache
entries programmatically. You can write your own scripts to call these functions at the
appropriate times.

5.4.3.3 Keeping the Cache Up To Date


If the cache entries are not purged when the data in the underlying databases changes,
then queries can potentially return results that are out of date. You must evaluate
whether this is acceptable. It might be acceptable to allow the cache to contain some
stale data. You must decide what level of stale data is acceptable and then configure
(and follow) a set of rules to reflect those levels.
For example, suppose an application analyzes corporate data from a large
conglomerate, and you are performing yearly summaries of the different divisions in
the company. New data does not materially affect the queries because the new data
affects only next year's summaries. In this case, the trade-offs for deciding whether to
purge the cache might favor leaving the entries in the cache.
Suppose, however, that the databases are updated three times a day and you are
performing queries on the current day's activities. In this case, you must purge the
cache much more often, or perhaps consider not using the cache at all.
Another scenario is that you rebuild the data mart from the beginning at periodic
intervals (for example, once per week). In this example, you can purge the entire cache
as part of the process of rebuilding the data mart, ensuring that you never have stale
data in the cache.
Whatever your situation, you must evaluate what is acceptable for noncurrent
information returned to the users.

5.4.3.4 CPU Usage and Disk I/O


Although usually it is very minor, query caching does require a small amount of CPU
time and adds to the disk I/O. In most cases, the CPU usage and disk I/O is
insignificant. The disk I/O might be noticeable only when queries return large data
sets.

5.4.4 Cache Sharing Across Users


If shared logon has been enabled for a particular connection pool, then the cache can
be shared across users and does not need to be seeded for each user. If shared logon
has not been enabled and a user-specific database login is used, then each user
generates a own cache entry.

Managing Performance Tuning and Query Caching 5-9


About the Oracle BI Server Query Cache

See Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business
Intelligence Enterprise Edition for information about enabling shared logon for
connection pools.

5.4.5 About the Refresh Interval for XML Data Sources


Typically, XML data sources are updated frequently and in real time. Setting a refresh
interval for XML data sources is analogous to setting cache persistence for database
tables. The refresh interval is a time interval after which the XML data sources are to
be queried again directly, rather than using results in cache. This refresh interval is
specified on the XML tab of the Connection Pool dialog.
The default interval setting is Infinite, meaning that the XML data source is not
automatically refreshed.
The refresh interval setting determines the time interval after which the Oracle BI
Server XML Gateway connection is refreshed, as follows:
For URLs that begin with http:// or https://, the gateway is refreshed when it
detects that the interval has expired.
For URLs that reside on a local or network drive, the gateway is refreshed when
the interval has expired and the system detects that the URLs have been modified.
For more information about XML data sources, see Oracle Fusion Middleware Metadata
Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition.

5.4.6 About the Global Cache


In a clustered environment, Oracle BI Servers can be configured to access a shared
cache called the global cache. This global cache resides on a shared file system storage
device and stores purging events, seeding events (often generated by agents), and
result sets that are associated with seeding events. The seeding and purging events are
sorted by time and stored on the shared storage as a logical event queue. Individual
Oracle BI Server nodes push to and pull from the logical event queue. Each Oracle BI
Server still maintains its own local query cache for regular queries.
Figure 51 depicts global caching in a clustered environment. It shows three Oracle BI
Server nodes sharing a global cache. The global cache stores seeding or purging events
held in a logical event queue. The arrows from Node 2 and Node 3 to the shared cache
show Oracle BI Server Node 2 pushing a seeding event to the queue and Oracle BI
Server Node 3 pushing a purging event to the queue. The arrows from the shared
storage to each Oracle BI Server node show each node pulling from the common
location. This occurs on a periodic basis and enables participating Oracle BI Server
nodes to obtain updates to the logical event queue made by other Oracle BI Servers.

5-10 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
About the Oracle BI Server Query Cache

Figure 51 Global Caching

The Oracle BI Server node processes a seeding or purging event locally first in its
caching system. It then pushes the event to the global cache on the shared storage.
During the push event, the active Oracle BI Server node locks the logical event queue
on the shared storage and then pushes in the seeding or purging event. If there is a
conflict between seeding and purging (for example, one node wants to seed a query
and another node wants to purge the same query), then the event that comes in last
wins.
The logical event queue in the global cache on the shared storage is composed of
seeding and purging events from individual Oracle BI Server nodes. The queue is
sorted according to the timestamp of the events. Hence, clocks on all Oracle BI Server
nodes participating in cluster must be synchronized.
Each Oracle BI Server node polls the global cache on a periodic basis for new cache
entries. This polling frequency is configurable. A snapshot of the queued logical events
on the shared storage are pulled back to the node and a local logical event queue is
constructed and then processed.

Note: The process of populating or purging seeded caches across all


Oracle BI Server nodes that participate in the cluster does not occur in
real time, and the elapse of the process is affected by multiple factors,
such as the predefined polling interval, network bandwidth, and CPU
loads.

Because the query cache result set tends to get large, network bandwidth might pose a
constraint. Therefore, the following must be chosen carefully:
The set of caches that qualify for seeded cache
The time interval for BI nodes to pick up seeded caches from shared storage (to
avoid network congestion)

Managing Performance Tuning and Query Caching 5-11


Configuring Query Caching

The primary global cache parameters are configured in Fusion Middleware Control.
Additional, optional parameters are configured in the NQSConfig.INI file for each
Oracle BI Server node that participates in the cluster. For more information about
configuring these parameters, see Section 5.5.4, "Using Fusion Middleware Control to
Set Global Cache Parameters" and Section 5.5.5, "Manually Editing Additional Global
Cache Parameters."
A seeding or purging procedure is submitted to a specific Oracle BI Server node. If
that Oracle BI Server is a node in a BI cluster and the global cache parameters have
been defined in Oracle BI Server configuration files, then the seeding or purging
events are propagated across all Oracle BI Server nodes that participate in the same
clustered environment.

5.5 Configuring Query Caching


You configure cache storage and other parameters in Fusion Middleware Control and
in the NQSConfig.INI file, for both the query cache and the global cache. You also
must decide on a strategy for flushing outdated cache entries; see Section 5.6,
"Monitoring and Managing the Cache" for more information.
This section contains the following topics:
Section 5.5.1, "Using Fusion Middleware Control to Enable and Disable Query
Caching"
Section 5.5.2, "Using Fusion Middleware Control to Set Query Cache Parameters"
Section 5.5.3, "Manually Editing Additional Query Cache Parameters"
Section 5.5.4, "Using Fusion Middleware Control to Set Global Cache Parameters"
Section 5.5.5, "Manually Editing Additional Global Cache Parameters"

5.5.1 Using Fusion Middleware Control to Enable and Disable Query Caching
You can use Fusion Middleware Control to enable or disable query caching. The query
cache is enabled by default.
Before you begin this procedure, ensure that you are familiar with the information in
Section 8.3.1, "Using Fusion Middleware Control".
To use Fusion Middleware Control to enable or disable query caching:
1. Go to the Business Intelligence Overview page, as described in Section 8.2.2,
"Displaying Oracle Business Intelligence Pages in Fusion Middleware Control."
2. Display the Performance tab of the Configuration page.
3. Click Lock and Edit to enable changes to be made.
4. To enable query caching, select Cache enabled. To disable query caching, deselect
Cache enabled.
Click the 'Help for this page' menu option to access the page-level help.
5. Click Apply, then click Activate Changes.
6. Return to the Business Intelligence Overview page and click Restart.
For information about corresponding configuration file elements, see Table C1,
" Performance Tab - Mapping Between User Interface Labels and Configuration File
Elements".

5-12 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Configuring Query Caching

5.5.2 Using Fusion Middleware Control to Set Query Cache Parameters


You can use Fusion Middleware Control to set the maximum number of cache entries
in the query cache and the maximum size for a single cache entry.
Before you begin this procedure, ensure that you are familiar with the information in
Section 8.3.1, "Using Fusion Middleware Control".
To use Fusion Middleware Control to set query cache parameters:
1. Go to the Business Intelligence Overview page, as described in Section 8.2.2,
"Displaying Oracle Business Intelligence Pages in Fusion Middleware Control."
2. Display the Performance tab of the Configuration page.
3. Click Lock and Edit to enable changes to be made.
4. Complete the elements using the descriptions in the help topic for the page.
Click the 'Help for this page' menu option to access the page-level help for the
following options:
Maximum cache entry size
Maximum cache entries
5. Click Apply, then click Activate Changes.
6. Return to the Business Intelligence Overview page and click Restart.
For information about corresponding configuration file elements, see Table C1,
" Performance Tab - Mapping Between User Interface Labels and Configuration File
Elements".

5.5.3 Manually Editing Additional Query Cache Parameters


You can set additional query cache parameters in the NQSConfig.INI file, including
the following:
The DATA_STORAGE_PATHS parameter specifies one or more directories for query
cache storage, and the maximum size for each storage directory. These directories
are used to store the cached query results and are accessed when a cache hit
occurs. See Section 5.7.1, "About Cache Hits" for more information about when
cache is hit.
The cache storage directories reside on high performance storage devices, ideally
devoted solely to cache storage. When the cache storage directories begin to fill
up, the entries that are least recently used (LRU) are discarded to make space for
new entries.
The MAX_ROWS_PER_CACHE_ENTRY parameter controls the maximum number of
rows for any cache entry. Limiting the number of rows is a useful way to avoid
using up the cache space with runaway queries that return large numbers of rows.
If the number of rows a query returns is greater than the value specified in the
MAX_ROWS_PER_CACHE_ENTRY parameter, then the query is not cached.
Typically, if a query gets a cache hit from a previously executed query, then the
new query is not added to the cache. The POPULATE_AGGREGATE_ROLLUP_HITS
parameter overrides this default when the cache hit occurs by rolling up an
aggregate from a previously executed query.
See Appendix A, "Configuration File Settings" for more information about the
additional query cache parameters.

Managing Performance Tuning and Query Caching 5-13


Monitoring and Managing the Cache

5.5.4 Using Fusion Middleware Control to Set Global Cache Parameters


Before you begin this procedure, ensure that you are familiar with the information in
Section 8.3.1, "Using Fusion Middleware Control".
To use Fusion Middleware Control to set global cache parameters:
1. Go to the Business Intelligence Overview page, as described in Section 8.2.2,
"Displaying Oracle Business Intelligence Pages in Fusion Middleware Control."
2. Display the Performance tab of the Configuration page.
3. Click Lock and Edit to enable changes to be made.
4. Complete the elements using the descriptions in the help topic for the page.
Click the 'Help for this page' menu option to access the page-level help for the
following options:
Global cache path
Global cache size
5. Click Apply, then click Activate Changes.
6. Return to the Business Intelligence Overview page and click Restart.
For information about corresponding configuration file elements, see Table C1,
" Performance Tab - Mapping Between User Interface Labels and Configuration File
Elements".

5.5.5 Manually Editing Additional Global Cache Parameters


You can set additional global cache parameters in the NQSConfig.INI file, including
the following:
The MAX_GLOBAL_CACHE_ENTRIES parameter controls the maximum number of
entries that are allowed in the global cache store.
The CACHE_POLL_SECONDS parameter specifies the interval in seconds at which the
Oracle BI Server pulls from the logical event queue to synchronize with other
server nodes in the cluster.
The CLUSTER_AWARE_CACHE_LOGGING parameter controls whether logging is turned
on for the global cache. Change this setting to YES only for debugging purposes.
Log entries appear in nqquery.log. You can find this file at:
BI_DOMAIN/servers/obisn/logs
See Appendix A, "Configuration File Settings" for more information about the
additional global cache parameters.

5.6 Monitoring and Managing the Cache


To manage the changes in the underlying databases and to monitor cache entries, you
must develop a cache management strategy. You need a process to invalidate cache
entries when the data in the underlying tables that compose the cache entry have
changed, and a process to monitor, identify, and remove any undesirable cache entries.
This section contains the following topics:
Section 5.6.1, "Choosing a Cache Management Strategy"
Section 5.6.2, "Purging and Maintaining Cache Using ODBC Procedures"

5-14 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Monitoring and Managing the Cache

Section 5.6.3, "How Repository Changes Affect the Query Cache"

5.6.1 Choosing a Cache Management Strategy


The choice of a cache management strategy depends on the volatility of the data in the
underlying databases and the predictability of the changes that cause this volatility. It
also depends on the number and types of queries that comprise your cache and the
usage those queries receive. This section provides an overview of the various
approaches to cache management.

5.6.1.1 Disable Caching for the System


You can disable caching for the entire system to stop all new cache entries and stop
any new queries from using the existing cache. Disabling caching lets you enable it at a
later time without losing any entries that are stored in the cache.
Temporarily disabling caching is a useful strategy in situations where you might
suspect having stale cache entries, but want to verify if they are actually stale before
purging those entries or the entire cache. If you find that the data stored in the cache is
still relevant, or after you have safely purged problem entries, then you can safely
enable the cache. If necessary, purge the entire cache or the cache that is associated
with a particular business model before enabling the cache again.
See Section 5.5.1, "Using Fusion Middleware Control to Enable and Disable Query
Caching" for more information.

5.6.1.2 Caching and Cache Persistence Timing for Specified Physical Tables
You can set a cacheable attribute for each physical table, enabling you to specify
whether queries for that table are added to the cache to answer future queries. If you
enable caching for a table, then any query involving the table is added to the cache. All
tables are cacheable by default, but some tables might not be good candidates to
include in the cache unless you use the Cache Persistence Time settings. For example,
suppose that you have a table that stores stock ticker data that is updated every
minute. You could use the Cache Persistence Time settings to purge the entries for that
table every 59 seconds.
You can also use the Cache persistence time field to specify how long the entries for
this table are stored in the query cache. This is useful for data sources that are updated
frequently.
To set the caching attributes for a specific physical table:
1. In the Administration Tool, in the Physical layer, double-click the physical table.
2. In the Physical Table properties dialog, in the General tab, make one of the
following selections:
To enable caching, select Cacheable.
To prevent a table from being cached, deselect Cacheable.
3. To set a cache expiration time, specify a Cache persistence time and specify a unit
of measure (days, hours, minutes, or seconds). If you do not want cache entries to
automatically expire, select Cache never expires.
4. Click OK.

5.6.1.3 Configure Oracle BI Server Event Polling Tables


Oracle BI Server event polling tables store information about updates in the
underlying databases. An application (such as one that loads data into a data mart)

Managing Performance Tuning and Query Caching 5-15


Monitoring and Managing the Cache

could be configured to add rows to an event polling table each time a database table is
updated. The Oracle BI Server polls this table at set intervals and invalidates any cache
entries corresponding to the updated tables. Event polling tables can be the sole
method of cache management, or they can be used with other cache management
schemes. Event tables offer less flexibility about choice of cache entries and the timing
of purges. See Section 5.8.1, "Setting Up Event Polling Tables on the Physical
Databases" for more information about event polling tables.

5.6.2 Purging and Maintaining Cache Using ODBC Procedures


The Oracle BI Server provides ODBC-extension functions for purging cache entries.
Some of these functions are particularly useful for embedding in an Extract,
Transform, and Load (ETL) task. For example, after a nightly ETL is performed, all
Oracle BI Server cache entries can be purged. If only the fact table was modified, then
only cache related to that table can be purged. In some cases, you might need to purge
the cache entries associated with a specific database.
Only administrators have the right to purge cache. Therefore, scripts that call these
ODBC-extension functions must run under credentials with administrator privileges.
The following ODBC functions affect cache entries that are associated with the
repository specified by the ODBC connection:
SAPurgeCacheByQuery. Purges cache entries that exactly match a specified query.
For example, using the following query, you would have one or more query cache
entries that retrieve the names of all employees earning more than $100,000:
SELECT lastname, firstname FROM employee WHERE salary > 100000;

The following call purges the cache entries that are associated with this query:
Call SAPurgeCacheByQuery('SELECT lastname, firstname FROM employee WHERE
salary > 100000' );

SAPurgeCacheByTable. Purges all cache entries that are associated with a


specified physical table name (fully qualified) for the repository to which the client
has connected.
This function takes up to four parameters that represent the four components
(database, catalog, schema, and table name proper) of a fully qualified physical
table name. For example, you might have a table with the fully qualified name of
DBName.CatName.SchName.TabName. To purge the cache entries that are associated
with this table in the physical layer of the Oracle Business Intelligence repository,
run the following call in a script:
Call SAPurgeCacheByTable( 'DBName', 'CatName', 'SchName', 'TabName' );

Note: Wildcards are not supported by the Oracle BI Server for this
function. In addition, DBName and TabName cannot be null. If either
one is null, then an error message is displayed.

SAPurgeAllCache. Purges all cache entries. The following is an example of this


call:
Call SAPurgeAllCache();

SAPurgeCacheByDatabase. Purges all cache entries associated with a specific


physical database name. A record is returned when any of the ODBC procedures

5-16 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Monitoring and Managing the Cache

to purge the cache are called. This function takes one parameter that represents the
physical database name, and the parameter cannot be null. The following shows
the syntax of this call:
Call SAPurgeCacheByDatabase( 'DBName' );

5.6.2.1 About ODBC Procedure Syntax


If there is a single quotation mark within the string argument of a procedure, then you
must use another single quotation mark to escape it. For example:
Call SAPurgeCacheByQuery('SELECT TOPN("- Currency"."Markdown %", 10) saw_0,
"XX Line"."Order No" saw_1, "- Bill-To Site"."Customer Name" saw_2, "-
Currency"."Net USD" saw_3, "- Currency"."Markdown USD" saw_4, "-
Currency"."Markdown %" saw_5 FROM "Apps 11i - XX Lines" WHERE
("XX Line"."Open Flag" = ''Y'') AND ("Operating Unit"."Group Name" = ''Group'')
AND ("- Currency"."Net USD" >= 10000) ORDER BY saw_0');

The line in bold highlights the extra single quotation marks that are used as escape
characters for the items ''Y'' and ''Group''.

5.6.2.2 About Sharing the Presentation Services Query Cache


When users access Answers to run queries, Presentation Services caches the results of
the queries. Presentation Services uses the request key and the logical SQL string to
determine if subsequent queries can use cached results. If the cache can be shared,
then subsequent queries are not stored.
SAGetSharedRequestKey: An ODBC procedure that takes a logical SQL
statement from Presentation Services and returns a request key value.
The following shows the syntax of this procedure:
SAGetSharedRequestKey('sql-string-literal')

The value of the request key is affected by the following factors:


Whether the Virtual Private Database option has been selected in the repository
physical database object
Whether any session variables have been marked as Security Sensitive in the
repository
Presentation Services takes security sensitive variable values into consideration when
computing the request key for logical requests against database objects marked as
Virtual Private Databases.
See Section 5.9, "Managing the Oracle BI Presentation Services Cache Settings" for
more information about the Presentation Services query cache.

5.6.2.3 About Result Records


A result record is returned after you issue a purge cache command. The result record
contains two columns. The first column is a result code and the second column is a
short message that describes the result of the purge operation. Table 51 shows
examples of result records.

Table 51 Query Result Codes


Result Code Result Message
1 SAPurgeCacheByDatabase returns successfully.

Managing Performance Tuning and Query Caching 5-17


Monitoring and Managing the Cache

Table 51 (Cont.) Query Result Codes


Result Code Result Message
59115 Operation not performed because caching is not enabled.
59116 The database specified does not exist.
59117 The table specified does not exist.

5.6.2.4 Storing and Purging Cache for SAP/BW Data Sources


In Microsoft Analysis Services, member caption name is the same as member unique
name. However, in SAP/BW data sources, member caption name is different from
member unique name. Therefore, the Oracle BI Server maintains a cache subsystem for
SAP/BW member unique names. This subsystem is turned off by default. For
configuration information, see the topic about the MDX Member Name Cache Section
in Appendix A, "Configuration File Settings."
When a query is received for member unique name, the subsystem checks the cache to
determine whether cache exists for this query. If cache exists, then the record for the
cached unique name is returned. If there is no cache that matches the query, then the
subsystem sends a probing query to SAP/BW.
The probing query is logged when the log level is equal or greater than 2. The status of
the subsystem, such as if the subsystem is enabled and events such as start and
shutdown events, are also written to the server log.

Caution: With each increased logging level, performance is


impacted. Use caution when increasing the log level for users.

Be aware of the following cache purge issues:


The size of multidimensional cache entries can grow very large. Therefore, a limit
on the size of each member set has been established in the MDX_MEMBER_CACHE
section of the NQSConfig.INI file.
The format of persisted cache might not be consistent after an upgrade. Therefore,
purge all cache before a software upgrade.
The cache is populated the first time that the query runs. Arrange to populate the
cache during off-peak hours, to minimize performance impact.

Note: In the Administration Tool, you can purge cache for an


individual cube table by right-clicking the cube table, and then
selecting Purge Member Cache. This must be performed in online
mode by a user with administrator privileges.

The following purge procedures are specific to SAP/BW data sources:


SAPurgeALLMCNCache. Purges all SAP/BW cache entries.
The following shows the syntax of this procedure:
SAPurgeALLIMCNCache ()

SAPurgeMCNCacheByCube. Purges all cache entries that are associated with the
specified physical cube. The database name and cube name are the external names
of the repository objects. The following shows the syntax of this procedure:

5-18 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Monitoring and Managing the Cache

SAPurgeMCNCacheByCube( 'DBName', 'CubeName')

Table 52 describes the messages that are returned.

Table 52 SAP Purge Cache Return Codes and Messages


Return Code Return Message
1 SAPurgeALLMCNCache returns successfully.
1 SAPurgeMCNCacheByCube returns successfully.
59116 The database specified does not exist.
Note: If the database and physical cube are both wrong, then
this result code is returned.
85025 The physical cube specified does not exist.

Only users with administrative privileges can run ODBC purge procedures.

5.6.3 How Repository Changes Affect the Query Cache


When you modify Oracle Business Intelligence repositories, the changes can have
implications for entries that are stored in the cache. For example, if you change the
definition of a physical object or a dynamic repository variable, cache entries that
reference that object or variable might no longer be valid. These changes might result
in the need to purge the cache. There are three scenarios to be aware of: when the
changes occur in online mode, when they occur in offline mode, and when you are
switching between repositories.

5.6.3.1 Online Mode


When you modify an Oracle Business Intelligence repository in online mode, any
changes that you make that affect cache entries automatically result in a purge of all
cache entries that reference the changed objects. The purge occurs when you check in
the changes. For example, if you delete a physical table from a repository, then all
cache entries that reference that table are purged upon check in. Any changes made to
a business model in the Business Model and Mapping layer purge all cache entries for
that business model.

5.6.3.2 Offline Mode


When you modify an Oracle Business Intelligence repository in offline mode, you
might make changes that affect queries that are stored in the cache and render those
cached results obsolete. Because the repository is not loaded by the server during
offline mode edits, the server has no way of determining if the changes made affect
any cached entries. The server therefore does not automatically purge the cache after
offline changes. If you do not purge the cache, then there might be invalid entries
when the repository is next loaded. Unless you are sure that there are no entries in the
cache that are affected by your offline changes, then purge the cache for any business
model that you have modified.

5.6.3.3 Switching Between Repositories


If you intend to remove a repository from the configuration of the Oracle BI Server,
then ensure that you purge the cache of all cache entries that reference the repository.
Failure to do so results in a corrupted cache. See Section 5.7.4.2, "Purging Cache in the
Administration Tool" for more information.

Managing Performance Tuning and Query Caching 5-19


Strategies for Using the Cache

5.6.3.4 Changes to Dynamic Repository Variables


The values of dynamic repository variables are refreshed by data that is returned from
queries. When you define a dynamic repository variable, you create an initialization
block or use a preexisting one that contains a SQL query. You also configure a schedule
for the Oracle BI Server to follow to execute the query and periodically refresh the
value of the variable.
When the value of a dynamic repository variable changes, all cache entries that are
associated with a business model that reference the value of that variable are purged
automatically. The cache entries are purged when the repository variable refresh rate is
reached, if its value has changed.
Note that if a business model is not associated with a changed dynamic repository
variable, then no cache purging action occurs. For example, suppose an initialization
block has been defined with a repository variable and a refresh rate of 5 minutes. But,
no logical column has been defined that references the variable. When the value of the
dynamic repository variable changes, cache is not purged because no logical column
exists within a business model that uses the variable.

5.7 Strategies for Using the Cache


One of the main advantages of query caching is to improve apparent query
performance. It might be valuable to seed the cache during off hours by running
queries and caching their results. A good seeding strategy requires that you know
when cache hits occur.
To seed the cache for all users, then you might seed the cache with the following
query:
SELECT User, SRs

After seeding the cache using SELECT User, SRs, the following queries are cache hits:
SELECT User, SRs WHERE user = valueof(nq_SESSION.USER) (and the user was USER1)
SELECT User, SRs WHERE user = valueof(nq_SESSION.USER) (and the user was USER2)
SELECT User, SRs WHERE user = valueof(nq_SESSION.USER) (and the user was USER3)

This section contains the following topics:


Section 5.7.1, "About Cache Hits"
Section 5.7.2, "Running a Suite of Queries to Populate the Cache"
Section 5.7.3, "Using Agents to Seed the Oracle BI Server Cache"
Section 5.7.4, "Using the Cache Manager"

5.7.1 About Cache Hits


When caching is enabled, each query is evaluated to determine whether it qualifies for
a cache hit. A cache hit means that the server was able to use cache to answer the
query and did not go to the database at all. The Oracle BI Server can use the query
cache to answer queries at the same or higher level of aggregation.
Many factors determine whether cache is hit. Table 53 describes these factors.

5-20 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Strategies for Using the Cache

Table 53 Factors That Determine Whether Cache Is Hit


Factor or Rule Description
A subset of columns in the All of the columns in the SELECT list of a new query have to exist in the cached query
SELECT list must match to qualify for a cache hit, or they must be able to be calculated from the columns in
the query.
This rule describes the minimum requirement to hit the cache, but meeting this rule
does not guarantee a cache hit. The other rules listed in this table also apply.
Columns in the SELECT list The Oracle BI Server can calculate expressions on cached results to answer the new
can be composed of query, but all the columns must be in the cached result. For example, the query:
expressions on the
SELECT product, month, averageprice FROM sales WHERE year = 2000
columns of the cached
queries hits cache on the query:
SELECT product, month, dollars, unitsales FROM sales WHERE year = 2000
because averageprice can be computed from dollars and unitsales (averageprice
= dollars/unitsales).
WHERE clause must be For the query to qualify as a cache hit, the WHERE clause constraints must be either
semantically the same or a equivalent to the cached results, or a subset of the cached results.
logical subset
A WHERE clause that is a logical subset of a cached query qualifies for a cache hit if the
subset meets one of the following criterion:
A subset of IN list values. Queries requesting fewer elements of an IN list cached
query qualify for a cache hit. For example, the following query:
SELECT employeename, region
FROM employee, geography
WHERE region in ('EAST', 'WEST')
qualifies as a hit on the following cached query:
SELECT employeename, region
FROM employee, geography
WHERE region in ('NORTH', 'SOUTH', 'EAST', 'WEST')
It contains fewer (but identical) OR constraints than the cached result.
It contains a logical subset of a literal comparison. For example, the following
predicate:
WHERE revenue < 1000
qualifies as a cache hit on a comparable query with the predicate:
WHERE revenue < 5000
There is no WHERE clause. If a query with no WHERE clause is cached, then queries
that satisfy all other cache hit rules qualify as cache hits regardless of their WHERE
clause.
In addition columns that are used on the WHERE clause must be on the projection list.
For example, the following query:
SELECT employeename
FROM employee, geography
WHERE region in ('EAST', 'WEST')
Does not result in a cache hit for the seeding query in the previous list because
REGION is not on the projection list.
Dimension-only queries If a query is dimension only, meaning that no fact or measure is included in the
must be an exact match query, then only an exact match of the projection columns of the cached query hits
the cache. This behavior prevents false positives when there are multiple logical
sources for a dimension table.

Managing Performance Tuning and Query Caching 5-21


Strategies for Using the Cache

Table 53 (Cont.) Factors That Determine Whether Cache Is Hit


Factor or Rule Description
Queries with special Other queries that contain special functions such as time series functions (AGO,
functions must be an exact TODATE, and PERIODROLLING), limit and offset functions (OFFSET and FETCH),
match relationship functions (ISANCESTOR, ISLEAF, ISROOT, and ISSIBLING), external
aggregation functions, and generally filter metrics must also be an exact match with
the projection columns in the cached query. In these cases, the filter must also be an
exact match. For filter metrics, if the filter metric can be rewritten as a WHERE clause,
then the subset cache might be leveraged.
Set of logical tables must To qualify as a cache hit, all incoming queries must have the same set of logical tables
match as the cache entry. This rule avoids false cache hits. For example, SELECT * FROM
product does not match SELECT * FROM product, sales.
Session variable values If the logical SQL or physical SQL statement refers to any session variable, then the
must match, including session variable values must match. Otherwise, the cache is not hit.
security session variables
In addition, the value of session variables that are security sensitive must match the
security session variable values that are defined in the repository, even though the
logical SQL statement itself does not reference session variables. See Section 5.7.1.1,
"Ensuring Correct Cache Results When Using Row-Level Database Security" for
more information.
Equivalent join conditions The resultant joined logical table of a new query request has to be the same as (or a
subset of) the cached results to qualify for a cache hit.
DISTINCT attribute must If a cached query eliminates duplicate records with DISTINCT processing (for
be the same example, SELECT DISTINCT...), then requests for the cached columns must also
include the DISTINCT processing; a request for the same column without the
DISTINCT processing is a cache miss.
Queries must contain Queries that request an aggregated level of information can use cached results at a
compatible aggregation lower level of aggregation. For example, the following query requests the quantity
levels sold at the supplier and region and city level:
SELECT supplier, region, city, qtysold
FROM suppliercity
The following query requests the quantity sold at the city level:
SELECT city, qtysold
FROM suppliercity
The second query results in a cache hit on the first query.
Limited additional For example, if a query with the column qtysold is cached, then a request for
aggregation RANK(qtysold) results in a cache miss. Additionally, a query that requests qtysold at
the country level can get a cache hit from a query that requests qtysold at the
country, region level.
ORDER BY clause must be Queries that order by columns that are not contained in the select list result in cache
comprised of columns in misses.
the select list
Avoiding cache misses You can avoid some cache misses by setting the parameter USE_ADVANCED_HIT_
using advanced hit DETECTION to YES in the NQSConfig.INI file. Advanced hit detection enables an
detection expanded search of the cache for hits. See "USE_ADVANCED_HIT_DETECTION" for
more information.
Diagnosing cache hit To better assess cache hit behavior, set the ENABLE_CACHE_DIAGNOSTICS session
behavior variable to 4, as shown in the following example:
ENABLE_CACHE_DIAGNOSTICS=4

5.7.1.1 Ensuring Correct Cache Results When Using Row-Level Database Security
When using a row-level database security strategy, such as a Virtual Private Database
(VPD), the returned data results are contingent on the authorization credentials of the

5-22 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Strategies for Using the Cache

user. Because of this, the Oracle BI Server must know whether a data source is using
row-level database security and which variables are relevant to security.
To ensure that cache hits only occur on cache entries that include and match all
security-sensitive variables, you must correctly configure the database object and
session variable objects in the Administration Tool, as follows:
Database object. In the Physical layer, in the General tab of the Database dialog,
select Virtual Private Database to specify that the data source is using row-level
database security.
If you are using row-level database security with shared caching, then you must
select this option to prevent the sharing of cache entries whose security-sensitive
variables do not match.
Session Variable object. For variables that you are using for authentication, in the
Session Variable dialog, select Security Sensitive to identify them as sensitive to
security when using a row-level database security strategy. This option ensures
that cache entries are marked with the security-sensitive variables, enabling
security-sensitive variable matching on all incoming queries.
Refer to the following resources for more information:
"Setting Up Row-Level Security in the Database" in Oracle Fusion Middleware
Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition
"Managing Session Variables" in Oracle Fusion Middleware Security Guide for Oracle
Business Intelligence Enterprise Edition
Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business
Intelligence Enterprise Edition for general information about database and session
variable objects

5.7.2 Running a Suite of Queries to Populate the Cache


To maximize potential cache hits, one strategy is to run a suite of queries to populate
the cache. The following are some recommendations for the types of queries to use
when creating a suite of queries with which to seed the cache.
Common prebuilt queries. Queries that are commonly run, particularly ones that
are expensive to process, are excellent cache seeding queries. Queries whose
results are embedded in dashboards are good examples of common queries.
SELECT lists with no expressions. Eliminating expressions on SELECT list
columns expands the possibility for cache hits. A cached column with an
expression can only answer a new query with the same expression; a cached
column with no expressions can answer a request for that column with any
expression. For example, a cached request such as:
SELECT QUANTITY, REVENUE...

can answer a new query such as:


SELECT QUANTITY/REVENUE...

but not the reverse.


No WHERE clause. If there is no WHERE clause in a cached result, then it can be
used to answer queries that satisfy the cache hit rules for the select list with any
WHERE clause that includes columns in the projection list.
In general, the best queries to seed cache with are queries that heavily consume
database processing resources and that are likely to be reissued. Be careful not to seed

Managing Performance Tuning and Query Caching 5-23


Strategies for Using the Cache

the cache with simple queries that return many rows. These queries (for example,
SELECT * FROM PRODUCTS, where PRODUCTS maps directly to a single database table)
require very little database processing. Their expense is network and disk overhead,
which are factors that caching does not alleviate.
When the Oracle BI Server refreshes repository variables, it examines business models
to determine if they reference those repository variables. If they do, the Oracle BI
Server then purges all cache for those business models. See Section 5.6.3.4, "Changes to
Dynamic Repository Variables" for more information.

5.7.3 Using Agents to Seed the Oracle BI Server Cache


You can configure agents to seed the Oracle BI Server cache. Seeding the cache can
improve response times for users when they run analyses or view analyses that are
embedded on their dashboards. You can accomplish this by scheduling agents to
execute requests that refresh this data.
To configure an agent to seed the Oracle BI Server cache:
1. Log in to Oracle Business Intelligence and select New, then select Agent.
2. On the General tab, select Recipient for the Run As option. Personalized cache
seeding uses the data visibility of each recipient to customize agent delivery
content for each recipient.
3. On the Schedule tab, specify when you want the cache to be seeded.
4. Optionally, select Condition and create or select a conditional request. For
example, you might have a business model that determines when the ETL process
is complete. You could use a report based on this business model to be the
conditional trigger for the cache seed to begin.
5. On the Delivery Content tab, select an individual request or an entire dashboard
page for which you want to seed the cache. Selecting a dashboard page can save
time.
6. On the Recipients tab, select individual users or groups to be the recipients.
7. On the Destinations tab, clear all user destinations and select Oracle BI Server
Cache.
8. Save the agent by selecting the Save button in the upper-right corner.
The only difference between cache seeding agents and other agents is that they clear
the previous cache automatically and do not appear on the dashboard as Alerts.
Note that cache seeding agents only purge exact match queries, so stale data might
still exist. Ensure that the caching strategy always include cache purging, because
agent queries do not address ad-hoc queries or drills.

5.7.4 Using the Cache Manager


The Cache Manager lets you view information about the entire query cache and
information about individual entries in the query cache that are associated with the
open repository. You can also use it to select specific cache entries and perform various
operations on those entries, such as viewing and saving the cached SQL statement, or
purging them.
To open the Cache Manager:
1. In the Administration Tool toolbar, select Manage, then Cache.

5-24 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Strategies for Using the Cache

Select the Cache tab on the left explorer pane to view the cache entries for the current
repository, business models, and users. The associated cache entries are reflected in the
right pane, with the total number of entries shown in the view-only field at the top.
You can control the cache entry information and its display sequence using the
Options settings (select Edit, then select Options from the Cache Manager, or select
Tools, then Options, then Cache Manager from the Administration Tool menu).
Information can include the options that are described in Table 54.

Table 54 Cache Options


Option Description
User The ID of the user who submitted the query that resulted in the
cache entry.
Created The time the cache entry's result set was created.
Last used The last time the cache entry's result set satisfied a query. (After
an unexpected shutdown of the Oracle BI Server, the last used
time might temporarily have a stale valuea value that is older
than the true value.)
Creation elapsed time The time, in seconds, that is needed to create the result set for
this cache entry.
Note: The value that is stored in the cache object descriptor on
disk is in units of milliseconds. The value is converted to
seconds for display purposes.
Row count The number of rows generated by the query.
Row size The size of each row (in bytes) in this cache entry's result set.
Full size Full size is the maximum size used, considering variable length
columns, compression algorithm, and other factors. The actual
size of the result set is smaller than Full size.
Column count The number of columns in each row of this cache entry's result
set.
Logical Request The logical request that is associated with this cache entry. If
subrequests are being cached, then this column shows the text
of the subrequest.
Use count The number of times that this cache entry's result set has
satisfied a query (since Oracle BI Server startup).
Business model The name of the business model that is associated with the
cache entry.
Repository The name of the Oracle Business Intelligence repository that is
associated with this cache entry.
SQL The SQL statement that is associated with this cache entry. If
subrequests are being cached, then there might be multiple
cache entries that are associated with a single SQL statement.
Query Server The Oracle BI Server that serviced the query.
Fact Table Source The fact table that is associated with the logical request for this
cache entry.

Expand the repository tree to display all the business models with cache entries, and
expand the business models to display all users with cache entries. The right pane
displays only the cache entries associated with the selected item in the hierarchical
tree.

Managing Performance Tuning and Query Caching 5-25


Strategies for Using the Cache

5.7.4.1 Displaying Global Cache Information in the Cache Manager


Select Action, then select Show Info to display global cache information. Table 55
describes the information that appears in the Global Cache Information window.

Table 55 Global Cache Information


Column Description
Amount of space still The amount of space, in megabytes, still available for cache
available for cache storage storage.
use
Amount of space used on The total amount of space, in megabytes, used on the disk that
disks containing cache contains cache-related files (not just space used for the
related files cache-related files).
Maximum allowable The maximum number of entries that can be in the cache, from
number of entries in cache the MAX_CACHE_ENTRIES parameter in the NQSConfig.INI file.
Maximum allowable The maximum number of rows that are allowed for each cache
number of rows per cache entry's result set, from the MAX_ROWS_PER_CACHE_ENTRY
entry result set parameter in the NQSConfig.INI file.
Number of entries currently The current number of entries in the global cache. These entries
in cache might relate to multiple repositories.
Number of queries not Cache misses, since the last time the Oracle BI Server was
satisfied from cache since started.
startup of Oracle BI Server
Number of queries satisfied Cache hits, since the last time the Oracle BI Server was started.
from cache since startup of
Oracle BI Server

With the Cache Manager as the active window, press F5, or select Action, then Refresh
to refresh the display. This retrieves the current cache entries for the repository that
you have open and the current global cache information. If the DSN is clustered, then
information about all repositories in the cluster is displayed.

5.7.4.2 Purging Cache in the Administration Tool


Purging cache is the process of deleting entries from the query cache. You can purge
cache entries in the following ways:
Manually, using the Administration Tool Cache Manager facility (in online mode).
Automatically, by setting the Cache Persistence Time field in the Physical Table
dialog for a particular table.
Automatically, by setting up an Oracle BI Server event polling table.
Automatically, as the cache storage space fills up.

Note: You can also purge the cache programmatically using


ODBC-extension functions. See Section 5.6.2, "Purging and
Maintaining Cache Using ODBC Procedures" for more information.
In addition, cache can be purged when the value of dynamic
repository variables changes. See Section 5.6.3.4, "Changes to Dynamic
Repository Variables" for more information.

To manually purge cache entries in the Cache Manager:

5-26 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Cache Event Processing with an Event Polling Table

1. Use the Administration Tool to open a repository in online mode.


2. Select Manage, then Cache to open the Cache Manager dialog.
3. Select Cache or Physical mode by selecting the appropriate tab in the left pane.
4. Browse the explorer tree to display the associated cache entries in the right pane.
5. Select the cache entries to purge, and then select Edit, then Purge to remove them.
Or, right-click the selected entries and then select Purge.
In Cache mode, select the entries to purge from those displayed in the right
pane.
In Physical mode, select the database, catalog, schema or tables to purge from
the explorer tree in the left pane.
In Cache mode, you can purge:
One or more selected cache entries that are associated with the open
repository.
One or more selected cache entries that are associated with a specified
business model.
One or more selected cache entries that are associated with a specified user
within a business model.
In Physical mode, you can purge:
All cache entries for all tables that are associated with one or more selected
databases.
All cache entries for all tables that are associated with one or more selected
catalogs.
All cache entries for all tables that are associated with one or more selected
schemas.
All cache entries that are associated with one or more selected tables.
Purging deletes the selected cache entries and associated metadata. Select Action, then
Refresh or press F5 to refresh the cache display.

5.8 Cache Event Processing with an Event Polling Table


You can use an Oracle BI Server event polling table (event table) as a way to notify the
Oracle BI Server that one or more physical tables have been updated. Each row that is
added to an event table describes a single update event, such as an update occurring
to the Product table in the Production database. The Oracle BI Server cache system
reads rows from, or polls, the event table, extracts the physical table information from
the rows, and purges stale cache entries that reference those physical tables.
The event table is a physical table that resides on a relational database accessible to the
Oracle BI Server. Regardless of whether it resides in its own database, or in a database
with other tables, it requires a fixed schema (described in Table 56). It is normally
exposed only in the Physical layer of the Administration Tool, where it is identified in
the Physical Table dialog as an Oracle BI Server event table.
Using event tables is one of the most accurate ways of invalidating stale cache entries,
and it is probably the most reliable method. It does, however, require the event table to
be populated each time that a database table is updated. Also, because there is a
polling interval in which the cache is not completely up to date, there is always the
potential for stale data in the cache. See Section 5.8.3, "Populating the Oracle BI Server

Managing Performance Tuning and Query Caching 5-27


Cache Event Processing with an Event Polling Table

Event Polling Table" for more information.


A typical method of updating the event table is to include SQL INSERT statements in
the extraction and load scripts or programs that populate the databases. The INSERT
statements add one row to the event table each time that a physical table is modified.
After this process is in place and the event table is configured in the Oracle Business
Intelligence repository, cache invalidation occurs automatically. As long as the scripts
that update the event table are accurately recording changes to the tables, stale cache
entries are purged automatically at the specified polling intervals.
This section contains the following topics:
Section 5.8.1, "Setting Up Event Polling Tables on the Physical Databases"
Section 5.8.2, "Making the Event Polling Table Active"
Section 5.8.3, "Populating the Oracle BI Server Event Polling Table"
Section 5.8.4, "Troubleshooting Problems with Event Polling Tables"

5.8.1 Setting Up Event Polling Tables on the Physical Databases


You can configure a physical event polling table on each physical database to monitor
changes in the database. You can also configure the event table in its own database.
The event table is updated every time a table in the database changes.
If the event polling table is on an Oracle Database, then configure the event table in its
own database object in the Physical layer of the Administration Tool. Then, ensure that
the feature PERF_PREFER_IN_LISTS is not selected in the Features tab of the Database
dialog for the event polling table. Following these guidelines avoids errors related to
exceeding the maximum number of allowed expressions in a list.
To create an event polling table, run the Repository Creation Utility (RCU) to create the
Business Intelligence Platform (BIPLATFORM) schemas in your physical database.
RCU creates an event polling table called S_NQ_EPT. See Oracle Fusion Middleware
Installation Guide for Oracle Business Intelligence for information about running the
Repository Creation Utility.
Event tables must have the structure that is shown in Table 56. Some columns can
contain null values, depending on where the event table resides. The names for the
columns must match the column names that are shown in Table 56. Data Types
shown are for Oracle Database.

Table 56 Event Polling Table Column Names


Event Table Column Data Type Description
CATALOG_NAME VARCHAR2 The name of the catalog where the physical table that
was updated resides.
Populate the CATALOG_NAME column only if the
event table does not reside in the same database as the
physical tables that were updated. Otherwise, set it to
the null value.

5-28 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Cache Event Processing with an Event Polling Table

Table 56 (Cont.) Event Polling Table Column Names


Event Table Column Data Type Description
DATABASE_NAME VARCHAR2 The name of the database where the physical table that
was updated resides. This is the name of the database
as it is defined in the Physical layer of the
Administration Tool. For example, if the physical
database name is 11308Production, and the database
name that represents it in the Administration Tool is
SQL_Production, then the polled rows in the event
table must contain SQL_Production as the database
name.
Populate the DATABASE_NAME column only if the
event table does not reside in the same database as the
physical tables that were updated. Otherwise, set it to
the null value.
OTHER_RESERVED VARCHAR2 Reserved for future enhancements. This column must
be set to a null value.
SCHEMA_NAME VARCHAR2 The name of the schema where the physical table that
was updated resides.
Populate the SCHEMA_NAME column only if the
event table does not reside in the same database as the
physical tables being updated. Otherwise, set it to a
null value.
TABLE_NAME VARCHAR2 The name of the physical table that was updated. The
name must match the name that is defined for the table
in the Physical layer of the Administration Tool.
Values cannot be null.
UPDATE_TS DATE The time when the update to the event table occurs.
This must be a key (unique) value that increases for
each row that is added to the event table. To ensure a
unique and increasing value, specify the current
timestamp as a default value for the column. For
example, specify DEFAULT CURRENT_TIMESTAMP for
Oracle Database.
Values cannot be null.
Note: Because this column must be a unique value that
increases for each row that is added to the event table,
you might need to set a very high precision if you
require many inserts per second. Because of this, you
might want to adjust the database feature FRACTIONAL_
SECOND_PRECISION to enable fractional seconds to be
used in the filters on the UpdateTime column. The
Oracle BI Server truncates the timestamps to the
number of digits that are defined by FRACTIONAL_
SECOND_PRECISION.
For example, for Oracle Database or Teradata, you
might want to change FRACTIONAL_SECOND PRECISION
from 0 to 6.
UPDATE_TYPE NUMBER Specify a value of 1 in the update script to indicate a
standard update. (Other values are reserved for future
use.)
Values cannot be null.

The Oracle BI Server must have read and write permission on the event polling table.
The server reads the event table at specified intervals to look for changed data.
Applications add rows to the event table when database tables are modified (for

Managing Performance Tuning and Query Caching 5-29


Cache Event Processing with an Event Polling Table

example, during a load operation). When there are rows in the event table, there is
changed data in the underlying databases. The server then invalidates any cache
entries that correspond to the changed physical tables and periodically deletes
obsolete rows from the event table. The next time it checks the event table, the process
repeats.

Note: In a clustered Oracle Business Intelligence deployment, a


single event polling table is shared by every Oracle BI Server node in
the cluster. However, a single event polling table cannot be shared by
multiple Oracle BI Server clusters.

To enable the Oracle BI Server to have write access to the event polling table but not to
any other tables in a database, perform the following tasks:
Create a separate physical database in the Physical layer of the Administration
Tool with a privileged connection pool.
Assign a user to the connection pool that has delete privileges.
Populate the privileged database with the event table.
The Oracle BI Server has write access to the event polling table, but not to any tables
that are used to answer user queries.

5.8.2 Making the Event Polling Table Active


After the table is created on the physical database, you can make it active in the Oracle
BI Server. To do this, you first import the physical table, and then you mark the table
object as an event polling table.
To import the physical table:
1. In the Administration Tool, open the repository and import metadata from the
physical database. To do this, select File, then select Import Metadata.
2. Follow the wizard steps. Be sure to select the Tables option in the Select Metadata
Types screen to import the table metadata.
See Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business
Intelligence Enterprise Edition for detailed information about the Import Metadata
wizard.
3. If you have multiple event polling tables, then repeat steps 1 and 2 for each event
table. Be sure the data source that is specified for the event table has read and
write access to the event table. The repository both reads the table and deletes
rows from it, so it needs write permission. Event tables do not need to be exposed
in the Business Model and Mapping layer.
To mark the table object as an event polling table:
1. From the Tools menu, select Utilities.
2. Select the option Oracle BI Event Tables from the list of options.
3. Click Execute.
4. Select the table to register as an Event Table and click the >> button.
5. Specify the polling frequency in minutes, and click OK.

5-30 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Managing the Oracle BI Presentation Services Cache Settings

The default value is 60 minutes. Do not set the polling frequency to less than 10
minutes. If you want a very short polling interval, then consider marking some or
all of the tables noncacheable.
When a table has been registered as an Oracle BI Server event table, the table
properties change. Registration as an event table removes the option to make the table
cacheable, as there is no reason to cache results from an event polling table.

5.8.3 Populating the Oracle BI Server Event Polling Table


The Oracle BI Server does not populate the event polling table. The event table is
populated by inserting rows into it each time that a table is updated. This process is
normally configured by the database administrator, who typically modifies the load
process to insert a row into the polling table each time a table is modified. This can be
done from the load script, using database triggers (in databases that support triggers),
from an application, or manually. If the process of populating the event table is not
done correctly, then the Oracle BI Server cache purging is affected, because the server
assumes the information in the polling table is correct and up to date.

5.8.4 Troubleshooting Problems with Event Polling Tables


If you experience problems with cache polling, then you can search the Oracle BI
Server activity logs for any entries regarding the server's interaction with the event
table.
The nqserver.log file logs activity automatically about the Oracle BI Server. Log
entries are self-explanatory and can be viewed in Fusion Middleware Control or in
a text editor.
When the Oracle BI Server polls the event table, it logs queries in the nqquery.log
file using the administrator account (set upon installation) unless the logging level
for the administrator account is set to 0. Set the logging level to 2 for the
administrator account to provide the most useful level of information.
You can find the nqserver.log and the nqquery.log in the following location:
BI_DOMAIN/servers/obisn/logs

5.9 Managing the Oracle BI Presentation Services Cache Settings


When users run analyses, Presentation Services can cache the results of those analyses.
Presentation Services determines if subsequent analyses can use cached results. If the
cache can be shared, then subsequent analyses are not stored.
The files for the Presentation Services cache have names such as nQS_xxxx_x_
xxxxxx.TMP. The files are created by the ODBC driver but generally do correspond to
ODBC requests that the Presentation Services cache keeps open. The files are stored in
the following directory:
BI_DOMAIN/servers/obips/tmp/obis_temp
The files for the cache are removed whenever Presentation Services shuts down
cleanly. If Presentation Services shuts down unexpectedly, then various cache files
might be left on disk. You can delete the files when Presentation Services is not
running.
The Presentation Services cache is different from the cache that is accessed by the
Oracle BI Server. You can change the defaults for the Presentation Services cache by
modifying the instanceconfig.xml file to include the cache entries.

Managing Performance Tuning and Query Caching 5-31


Managing the Oracle BI Presentation Services Cache Settings

The following procedure provides information about configuration changes with


which you can manage the Presentation Services cache.
See Section 5.6.2.2, "About Sharing the Presentation Services Query Cache" for
information about an ODBC procedure to use for sharing the cache.
To manually edit the settings for managing the cache:
1. Open the instanceconfig.xml file for editing in:
BI_DOMAIN/config/fmwconfig/biconfig/OBIPS
2. Locate the section in which you must add the elements that are described in
Table 57.

Note: Avoid specifying values of less than 3 minutes for the elements
that affect minutes. At such a low amount of time, refreshes can occur
frequently, which can negatively affect performance and cause
flickering on the screen.

3. Include the elements and their ancestor elements as appropriate, as shown in the
following example:
<ServerInstance>
<Cache>
<Query>
<MaxEntries>100</MaxEntries>
<MaxExpireMinutes>60</MaxExpireMinutes>
<MinExpireMinutes>10</MinExpireMinutes>
<MinUserExpireMinutes>10</MinUserExpireMinutes>
</Query>
</Cache>
</ServerInstance>

4. Save your changes and close the file.


5. Restart Oracle Business Intelligence.

Table 57 Elements for Configuring the Cache for Presentation Services


Element Description Default Value
MaxEntries Specifies the maximum number of open 500
record sets that Presentation Services keeps
open at any one time. The minimum value
is 3. For systems under significant loads,
you can increase this value to 700 or 1000.
MaxExpireMinutes Specifies the maximum amount of time, in 60
minutes, that an entry in the cache can
exist before it is removed. Depending on
the number of analyses being run, an entry
might be removed before the time limit
expires.
MinExpireMinutes Specifies the minimum amount of time, in 10
minutes, that an entry in the cache can
exist before it is removed. The setting for
CacheMinUserExpireMinutes can force an
entry for a particular user to exist for a
longer time than that specified by the
CacheMaxExpireMinutes element.

5-32 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Improving Oracle BI Web Client Performance

Table 57 (Cont.) Elements for Configuring the Cache for Presentation Services
Element Description Default Value
MinUserExpireMinutes Specifies the minimum amount of time, in 10
minutes, that an entry in the cache can
exist after it has been viewed by a user.
For example, if CacheMaxExpireMinutes is
set to 60 minutes and a user views the
entry during the 59th minute, the entry
exists for that user for an additional 10
minutes. The user can continue paging
through the data without requiring a new
analysis to be run.

5.10 Improving Oracle BI Web Client Performance


You can improve the performance of the Oracle BI web client by configuring the web
server to serve up all static files, as well as enabling compression for both static and
dynamic resources. By enabling caching and content expiration on the web server, web
browsers can determine how often to reload the static files from the server.
Follow the instructions for the web server to set up static file caching and compression
for the files located in this directory.

Note: See the following documents for full information about how to
configure Oracle WebLogic Server to work with web servers such as
Apache HTTP Server, Microsoft Internet Information Server
(Microsoft IIS), and Oracle HTTP Server:
Oracle Fusion Middleware Using Web Server 1.1 Plug-Ins with Oracle
WebLogic Server
Oracle Fusion Middleware Administrator's Guide for Oracle HTTP Server

The following sections provide example configurations:


Section 5.10.1, "Configuring Apache HTTP Server for Static File Caching"
Section 5.10.2, "Configuring Oracle HTTP Server for Static File Caching"

5.10.1 Configuring Apache HTTP Server for Static File Caching


This example configuration assumes that you have installed the web server plug-in
that enables Apache HTTP Server to proxy requests to Oracle WebLogic Server. Make
sure that the PLUGIN_HOME/lib directory is added to LD_LIBRARY_PATH, or
equivalent for your operating system.
The steps in this section show an example configuration only. You can adjust your
configuration as needed. See Oracle Fusion Middleware Using Web Server 1.1 Plug-Ins
with Oracle WebLogic Server for full information.
To add configuration directives for the plug-in:
1. Locate the httpd.conf file for your Apache HTTP Server.
2. Open the file for editing and add directives similar to the following:
LoadModule weblogic_module modules/mod_wl.so

<IfModule mod_weblogic.c>

Managing Performance Tuning and Query Caching 5-33


Improving Oracle BI Web Client Performance

WebLogicPort 9704
Debug OFF
WebLogicHost localhost
WLLogFile /tmp/wl-proxy.log
</IfModule>

<LocationMatch "/analytics/saw\.dll.*">
SetOutputFilter DEFLATE
SetHandler weblogic-handler
</LocationMatch>

<LocationMatch "/analytics/.*\.jsp.*">
SetOutputFilter DEFLATE
SetHandler weblogic-handler
</LocationMatch>

Note the following:


Modify the LoadModule directive based on where and how you installed the
plug-in.
The IfModule directive enables the connection to Oracle WebLogic Server. See
Oracle Fusion Middleware Using Web Server 1.1 Plug-Ins with Oracle WebLogic
Server for more information about the connectivity options, including how to
configure a cluster and SSL considerations.
The LocationMatch directives are used to route all dynamic requests to Oracle
WebLogic Server. Be sure to include the SetOutputFilter DEFLATE directive,
which enables GZip compression for all dynamic requests.
3. Save and close the file.
To add configuration directives for handling static files:
1. Locate the httpd.conf file for your Apache HTTP Server.
2. Open the file for editing and add directives similar to the following:
Alias /analytics ORACLE_HOME/bi/bifoundation/web/appv2
<Directory ORACLE_HOME/bi/bifoundation/web/appv2>
# Disable cross-server ETags
FileETag none
# Enable compression for all files
SetOutputFilter DEFLATE
# Don't compress images
SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png)$ no-gzip dont-vary
# Enable future expiry of static files
ExpiresActive on
ExpiresDefault "access plus 1 week"
Header set Cache-Control "max-age=604800"
DirectoryIndex default.jsp
</Directory>

# Restrict access to WEB-INF


<Location /analytics/WEB-INF>
Order Allow,Deny
Deny from all
</Location>

Note the following:

5-34 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Improving Oracle BI Web Client Performance

You must ensure that Apache HTTP Server has access to the static files for the
Oracle BI web client in ORACLE_HOME/bi/bifoundation/web/appv2.
Ensure that the web server is running and has read access to this location.
The Alias and Directory entries tell Apache HTTP Server to handle requests
for static files rather than routing them to Oracle WebLogic Server. Note the
following about the directives related to compression and static file expiry:
FileETag
FileETag none

This directive tells the web server to disable generation of ETag headers in
the response. Default ETag generation for Apache HTTP Server is tied to
the file system for a single server, so generating ETags is not recom-
mended.
Compression Related Directives
SetOutputFilter DEFLATE
# Don't compress images
SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png)$ no-gzip dont-vary

These directives ensure that Apache HTTP Server compresses all files
except images. Typically, images are already compressed and do not bene-
fit from additional compression.
Control of Expires Header
# Enable future expiry of static files
ExpiresActive on
ExpiresDefault "access plus 1 week"

This fragment tells Apache HTTP Server to enable setting the Expires
header. In this example, the default expiration is set to one week after the
first time the file was accessed by the client. You can increase this time
period, but ensure that static files are refreshed often enough to handle
any patches or updates made on the static files.
Control of the Cache-Control Header
Header set Cache-Control "max-age=604800"

This fragment tells Apache HTTP Server to set the Cache-Control header.
In this example, the default is set to one week (in seconds) to match the
Expires header. This value must always be kept in sync with the Expires
header. This header is required to force earlier versions of Microsoft Inter-
net Explorer to properly cache static files.
Handling Default URLs
DirectoryIndex default.jsp

This directive provides a fallback handler when a user requests the /ana-
lytics URL without specifying any content under it. This URL is then
routed to Oracle WebLogic Server for further processing.
The final directive restricts access to the WEB-INF folder. This folder is part of
the J2EE container's deployment descriptor and must not be exposed to web
clients.
3. Save and close the file.

Managing Performance Tuning and Query Caching 5-35


Setting the JVM Heap Size for Oracle Business Intelligence

5.10.2 Configuring Oracle HTTP Server for Static File Caching


Configuration for Oracle HTTP Server is similar to configuration for Apache HTTP
Server, except that you do not need to download and install the plug-in because the
mod_wl_ohs.so module is installed by default with Oracle HTTP Server. Some
configuration is performed in the mod_wl_ohs.so module directly, and some
configuration is performed in httpd.conf. See Oracle Fusion Middleware Administrator's
Guide for Oracle HTTP Server for full information.

5.11 Setting the JVM Heap Size for Oracle Business Intelligence
You can change the default JVM heap size for the Administration Server and Managed
Servers by setting the USER_MEM_ARGS parameter in the startup script for Oracle
WebLogic Server. The following procedure sets the same values for both the
Administration Server and Managed Servers.
For more information, see Oracle Fusion Middleware Managing Server Startup and
Shutdown for Oracle WebLogic Server.
To change the default JVM heap size:
1. Use the WebLogic Server Administration Console to shut down the servers
gracefully.
2. Open the setUserOverrides.sh file (or setUserOverrides.cmd on Windows
systems) for editing. You can create this file in:
BI_DOMAIN/bin
3. Set the -Xmx argument for USER_MEM_ARGS. The following list shows examples
of how to set USER_MEM_ARGS for various operating systems:
UNIX shell script (.sh)
USER_MEM_ARGS="-Xms256m -Xmx1024m -XX:CompileThreshold=8000
-xx:PermSize=128m -XX:MaxPermSize=512m"

Windows command script (.bat)


set USER_MEM_ARGS="-Xms256m -Xmx1024m -XX:CompileThreshold=8000
-xx:PermSize=128m -XX:MaxPermSize=512m"

Note: The arguments for USER_MEM_ARGS can vary, depending


on the JDK vendor.

4. After setting the parameter, save and close the file, then restart the Administration
Server and Managed Servers for the changes to take effect.
5. In a scaled-out system, repeat these steps for each domain home.
The settings are now copied over when you horizontally scale-out.

5.12 Capturing Metrics Using the Dynamic Monitoring Service


In addition to the Metrics Browser in Fusion Middleware Control, you can view
metrics for Oracle Business Intelligence using the Dynamic Monitoring Service (DMS)
and WLST commands. This section describes how to use these methods.

5-36 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Capturing Metrics Using the Dynamic Monitoring Service

5.12.1 Using the Dynamic Monitoring Service for Metrics


You can use the Dynamic Monitoring Service (DMS) to view metrics for Oracle
Business Intelligence. Access the service using the following URL:
http://<host>:<port>/dms
Using the Metrics Tables list in the left pane, select Non-J2EE Metrics to view the list
of metrics for Oracle Business Intelligence. This is the same list that you see in the
Metrics Browser of Fusion Middleware Control.
You can use the Dynamic Monitoring Service to quickly obtain a snapshot of metrics.
You can use the URL for a given metric as the source for a web query in a Microsoft
Excel spreadsheet that you combine with a macro that automatically copies values to
an archive sheet and refreshes the query on a loop for a given period.
Suppose that you want to use the Dynamic Monitoring Service to see the details of the
metric table called "Oracle_BI_General". When you click the Oracle_BI_General link
in the Metrics Tables list, the table is displayed on the right side. This metric table
consists of several monitored values, such as Active_Execute_Requests and Total_
Sessions. You can use the information from the tables that are displayed in this Metrics
Browser as part of WLST commands.
For information on accessing DMS metrics using WLST commands, see the chapter on
DMS custom WLST commands in Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference.

5.12.2 Using WLST Commands for Metrics


You can use WLST commands to capture metrics for Oracle Business Intelligence.
To use WLST commands for metrics:
1. Navigate to the ORACLE_HOME/oracle_common/common/bin directory.
2. Run the WLST utility.
3. Connect to the Oracle BI system using the connect command, as shown in the
following example:
connect('user','password','t3://<host><port>)
4. Verify that you are in "online mode" by viewing the following prompt:
wls:/bi/serverConfig>
You can now interactively use the DMS custom WLST commands. For example, to list
all the metric tables that start with "Oracle_BI", enter the following command:
wls:/bifoundation_domain/serverConfig> displayMetricTables('Oracle_BI*')
This command generates a long list of data for each of the Oracle BI metric tables. So it
is more useful to focus on a given metric table, such as "Oracle_BI_General". The
following command displays output such as that shown in this sample.
wls:/bifoundation_domain/serverConfig> displayMetricTables('Oracle_BI_
General')

-----------------
Oracle_BI_General
-----------------
Active_Execute_Requests.value: 0
Active_Fetch_Requests.value: 0
Active_File_Handles.value: 1

Managing Performance Tuning and Query Caching 5-37


Capturing Metrics Using the Dynamic Monitoring Service

Active_Initblock_Executions.value: 0
Active_Logins.value: 0
Active_Prepare_Requests.value: 0
Avg._Failed_Logins_Elapsed_Time.value: 0
Avg._Initblock_Executions_Elapsed_Time.value: 0
Avg._Succeeded_Logins_Elapsed_Time.value: 0
Avg._query_elapsed_time.value: 0
Busy_File_Handles.value: 0
File_Handle_Waiters.value: 0
Free_File_Handles.value: 502
Host: oracle-bc5ac6af
Max._Initblock_Execution_Elapsed_Time.value: 0
Max_File_Handles.value: 503
Name: Oracle BI General
New_Execute_Requests.value: 19
New_Fetch_Requests.value: 32
New_Initblock_Executions.value: 0
New_Logins.value: 7
New_Prepare_Requests.value: 19
New_Requests.value: 187
OBPERF_***.value: 7
Oracle_BI_Applications: Oracle BI Server
Parent: /Oracle BI Server
Process: Oracle BI Server:4004:/instance1/coreapplication_obis1
Queries/sec.value: 0
ServerName: /instance1/coreapplication_obis1
Succeeded_Initblock_Execution_Ratio_as_%.value: 0
Succeeded_Logins_Ratio_as_%.value: 7
Total_sessions.value: 0

Using the scripting capability of WLST, you can embed DMS commands into a Python
script to store the required metric values in a file. The following is an example of such
a script.
# Script to dump timestamp (in milliseconds) for a single Oracle BI metric
# to a file
#
from java.util import Date
from java.text import SimpleDateFormat
#
# Modify to connect to your server
connect('biadmin','welcome1','t3://localhost:9500')
#
# This is the number of times to sample the metric
sample_length = 100
#
# This is where you define what metric table and metric to dump to file
metric_table = "Oracle_BI_General"
metric_of_interest = "Avg._query_elapsed_time.value"
#
# Some metrics have non-text characters in the name. Provide a reference here
# so it dumps to file without error in file name
output_file_metric_ref = "Avg_Qry_Elapse"
#
# This section defines the output file name with unique time
start_time = str(SimpleDateFormat("dd-MMM-yyyy_HH-mm-ss").format(Date()))
output_filename = start_time + "_" + output_file_metric_ref + "_dump.txt"
#
# Open the file and write summary of metric to be dumped
file = open(output_filename,'w')

5-38 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Capturing Metrics Using the Dynamic Monitoring Service

print >>file, "Start Metric Dump of: " + str(metric_table) + " : " + str(metric_
of_interest) + " at " + str(SimpleDateFormat("dd-MMM-yyyy
HH-mm-ss").format(Date()))
#
#
# The following section forms a loop according to the sample length defined
# earlier. The 'displayMetricTables()' command returns the metric table in the
# form of a JMX composite data array. The code following this command access
# the metric data from this array. In this case, a particular metric of
# interest is tested for and only the value of that metric is output to file.
#
counter = 0
while counter <= sample_length:
results = displayMetricTables(metric_table)
for table in results:
name = table.get('Table')
rows = table.get('Rows')
rowCollection = rows.values()
iter = rowCollection.iterator()
while iter.hasNext():
row = iter.next()
rowType = row.getCompositeType()
keys = rowType.keySet()
keyIter = keys.iterator()
while keyIter.hasNext():
columnName = keyIter.next()
value = row.get(columnName)
if columnName == metric_of_interest:
print >>file, str(SimpleDateFormat("dd-MMM-yyyy
HH-mm-ss-SSS").format(Date())) + "," + str(value)
counter = counter + 1
file.close()
disconnect()

Certain Oracle BI metric tables, such as "Oracle_BI_Thread_Pool", are in effect


two-dimensional. With the "Oracle_BI_Thread_Pool" table, you can query the metric
values for various "Names", such as "Server" or "Usage_Tracking". To export the
required metric value to a file in this case, you must modify the logic that was used in
looping in the previous example script to handle the two dimensions. The following
example script provides one way to handle this case.
# Script to dump timestamp (in milliseconds) and a
#single Oracle BI metric to a file for metrics with multiple sections
#
from java.util import Date
from java.text import SimpleDateFormat
#
# Modify to connect to your server
connect('biadmin','welcome1','t3://localhost:9500')
#
# This is the number of times to sample the metric
sample_length = 100
#
# This is where you define what metric table, category, and metric to
# dump to file
metric_table = "Oracle_BI_Thread_Pool"
category_of_interest = "Server"
metric_of_interest = "Avg._Request/sec.value"
#
# Some metrics have non-text characters - provide a reference here

Managing Performance Tuning and Query Caching 5-39


Capturing Metrics Using the Dynamic Monitoring Service

# so it dumps to file without error


output_file_metric_ref = "Avg_Req_Sec"
#
# This section defines the output file name with unique time
start_time = str(SimpleDateFormat("dd-MMM-yyyy_HH-mm-ss").format(Date()))
output_filename = start_time + "_" + output_file_metric_ref + "_dump.txt"
#
# Open the file and write summary of metric to be dumped
file = open(output_filename,'w')
print >>file, "Start Metric Dump of: " + str(metric_table) + " : " + str(metric_
of_interest) + " for Category: " + str(category_of_interest) + " at " +
str(SimpleDateFormat("dd-MMM-yyyy HH-mm-ss").format(Date()))
#
#
counter = 0
while counter <= sample_length:
results = displayMetricTables(metric_table)
for table in results:
name = table.get('Table')
rows = table.get('Rows')
rowCollection = rows.values()
iter = rowCollection.iterator()
while iter.hasNext():
row = iter.next()
if row.containsValue(category_of_interest):
rowType = row.getCompositeType()
keys = rowType.keySet()
keyIter = keys.iterator()
while keyIter.hasNext():
columnName = keyIter.next()
value = row.get(columnName)
if columnName == metric_of_interest:
print >>file, str(SimpleDateFormat("dd-MMM-yyyy
HH-mm-ss-SSS").format(Date())) + "," + str(value)
counter = counter + 1
file.close()
disconnect()

5-40 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Part IV
Part IV Resolving Issues

This part explains how to resolve issues in Oracle Business Intelligence. It includes the
following chapters:
Chapter 6, "Diagnosing and Resolving Issues in Oracle Business Intelligence"
Chapter 7, "Managing Usage Tracking"
6
Diagnosing and Resolving Issues in Oracle
6

Business Intelligence

This chapter describes how to diagnose and resolve issues in Oracle Business
[7]

Intelligence using tools such as Fusion Middleware Control and log files.
This chapter includes the following sections:
What Diagnostic Tools Are Available?
Collecting Diagnostic Bundles
Viewing and Configuring Diagnostic Log Files
Understanding Diagnostic Log and Log Configuration Files
Managing the Query Log
Logging in Oracle BI Presentation Services
Using ODBC/JDBC Procedures to Obtain Oracle BI Server Diagnostics
Troubleshooting System Startup

6.1 What Diagnostic Tools Are Available?


Oracle Business Intelligence provides various diagnostic tools to assist you in finding
the causes and solutions to issues, as described in Table 61.

Table 61 Diagnostic Tools


Tool Description Reference
Diagnostic bundle Enables collection of log and Section 6.2, "Collecting Diagnostic
configuration information Bundles"
attachment for Oracle
Support requests
Overview page in Enables you to view recent Section 8.2.2, "Displaying Oracle
Fusion Middleware issues with the system. Business Intelligence Pages in Fusion
Control Middleware Control"
Performance metrics Enables you to view metrics Section 5.1, "Monitoring Service
that affect performance. Levels"

Diagnosing and Resolving Issues in Oracle Business Intelligence 6-1


Collecting Diagnostic Bundles

Table 61 (Cont.) Diagnostic Tools


Tool Description Reference
Diagnostic pages in Enables you to drill into Section 6.3.1, "Using Fusion
Fusion Middleware problems and view and Middleware Control to View Log
Control configure log files. Information, Error Messages, and
Alerts"
Section 6.3.2.1, "Using Fusion
Middleware Control to Configure Log
File Rotation Policy and Specify Log
Levels"
Usage tracking Enables you to generate Section 7.1, "About Usage Tracking"
usage tracking statistics that
can be used in a variety of
ways such as database
optimization, aggregation
strategies, or billing users or
departments based on the
resources that they consume.
Reports of Catalog Enables you to learn details Section 16.9, "Creating Reports to
objects of objects in the Oracle BI Display Catalog Data Using Catalog
Presentation Catalog. Manager"
Consistency Check Enables you to check the "Checking the Consistency of a
Manager validity of the repository. Repository or a Business Model" in
Oracle Fusion Middleware Metadata
Repository Builder's Guide for Oracle
Business Intelligence Enterprise Edition
Model Check Enables you to check for "Using Model Check Manager to
Manager modeling problems that Check for Modeling Problems" in
might affect Oracle BI Oracle Fusion Middleware Metadata
Summary Advisor and the Repository Builder's Guide for Oracle
aggregate persistence engine. Business Intelligence Enterprise Edition
ODBC/JDBC Enables you to obtain Section 6.7, "Using ODBC/JDBC
procedures diagnostic information for Procedures to Obtain Oracle BI Server
the Oracle BI Server. Diagnostics"

6.2 Collecting Diagnostic Bundles


This section explains how to collect diagnostic bundles needed by Oracle Support to
help resolve issues.
You must collect post configuration diagnostic bundles before Oracle Development or
Support will accept your bug or support request (SR) submissions.
Assumptions:
You must review the product FAQ.
BI Installation and configuration was successful, specifically the BI Configuration
Assistant has completed without error. If this isn't the case please see below for
details on how to collect diagnostics prior to contacting Oracle Support. If the BI
Configuration Assistant fails see New server configuration (BI Configuration
Assistant) in the Oracle Fusion Middleware Installation Guide for Oracle Business
Intelligence.
No security sensitive information is collected.
Pre-requisites:
You must have file system permissions

6-2 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Viewing and Configuring Diagnostic Log Files

To collect a diagnostic bundle:


1. Collect a diagnostic bundle by running the following command:
DOMAINHOME/bitools/bin/diagnostic_dump.sh <zip file name>.
2. Provide the zip file to the Support or Development organization when requested.

6.3 Viewing and Configuring Diagnostic Log Files


You can view diagnostic log files and configure settings that affect diagnostic log files
and the information that they contain, as described in the following sections:
Section 6.3.1, "Using Fusion Middleware Control to View Log Information, Error
Messages, and Alerts"
Section 6.3.2, "Configuring Log File Rotation Policy and Specifying Log Levels"

6.3.1 Using Fusion Middleware Control to View Log Information, Error Messages, and
Alerts
You can search for and view the log entries for Oracle Business Intelligence
components using Fusion Middleware Control Log Viewer. The log files can be
searched for log messages, and you can apply filters that can, for example, target a
certain date range, user, user transaction, or level of message (error, warning,
notification, and so on). You can also view log files in their entirety from the Fusion
Middleware Control Log Viewer.
When log entries for error messages and warnings are generated across multiple log
files, they can be difficult to trace. However, it is possible to view logging information
for specific user transactions across multiple log files. Transaction level logging
associates a unique transaction ID, which is called the Execution Context ID (ECID),
with every log and error message that is generated in response to a user request. This
logging enables rapid diagnosis of the cause of underlying issues. However, some
messages in the log (for example system messages for server startup or shutdown) do
not have a transactional attribute. All log messages that are related to client requests
do have a transactional attribute.
Before you begin this procedure, ensure that you are familiar with the information in
Section 8.3.1, "Using Fusion Middleware Control".
To use Fusion Middleware Control to view log information, error messages, and
alerts:
1. Go to the Business Intelligence Overview page, as described in Section 8.2.2,
"Displaying Oracle Business Intelligence Pages in Fusion Middleware Control."
2. Display the Log Messages tab of the Diagnostics page.
Click the 'Help for this page' menu option to access the page-level help for its
elements.
3. View lists of the following:
Recent errors under the Most Recent Errors region
recent warnings under the Most Recent Warnings region
4. Select a link under View/Search All Log Files and View/Search Log Files By
Component to display messages for all log files, or for the messages for the log
files of a specified component. Click the Help button on the page to access the
page-level help for the following links:

Diagnosing and Resolving Issues in Oracle Business Intelligence 6-3


Viewing and Configuring Diagnostic Log Files

Search the log files using the Log Viewer


Presentation Services Log
Server Log
Scheduler Log
JavaHost Log
Cluster Controller Log
Action Services Log
Security Services Log
Administrator Services Log
Fusion Middleware Control displays messages in the Log Messages page that
correspond to your selection.
5. Enter appropriate search criteria to display corresponding error messages.
To view messages by ECID, click View Related Messages and select the by ECID
(Execution Context ID) menu option.
6. Select one or more rows to view the log file entry details for the selected messages.
For more information about the elements that are displayed in the Log Viewer, see
the Fusion Middleware help.

6.3.2 Configuring Log File Rotation Policy and Specifying Log Levels
You can configure criteria that determine when a new log file must be created, based
on the size of the log file and the age of the log file. You can also specify log levels to
determine what level of message the log files contain.
This section contains the following topics:
Section 6.3.2.1, "Using Fusion Middleware Control to Configure Log File Rotation
Policy and Specify Log Levels"
Section 6.3.2.2, "Manually Changing Additional Log File Settings"

6.3.2.1 Using Fusion Middleware Control to Configure Log File Rotation Policy and
Specify Log Levels
Before you begin this procedure, ensure that you are familiar with the information in
Section 8.3.1, "Using Fusion Middleware Control".
To use Fusion Middleware Control to configure log file rotation policy and specify
log levels:
1. Go to the Business Intelligence Overview page, as described in Section 8.2.2,
"Displaying Oracle Business Intelligence Pages in Fusion Middleware Control."
2. Display the Log Configuration tab of the Diagnostics page.
3. Click Lock and Edit to enable changes to be made.
4. Complete the elements using the descriptions in the help topic for the page.
For example, you can specify which log levels to use, and for some you can set
their granularity.
Click the 'Help for this page' menu option to access the page-level help for the
following options:

6-4 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Viewing and Configuring Diagnostic Log Files

Log Configuration
Maximum File Size option
Maximum Log Age option
Query Logs
Maximum File Size option
Maximum Log Age option
Default Log Level
Component Specific Log Levels
5. Click Apply, then click Activate Changes.
6. Return to the Business Intelligence Overview page and click Restart.

6.3.2.2 Manually Changing Additional Log File Settings


In addition to the log file settings that you can change in Fusion Middleware Control,
you can change other settings manually. Use various elements in the log configuration
file for a component to change these settings.
To manually change the settings that configure the log file format:
1. Open the component log configuration file located in:
BI_DOMAIN/config/fmwconfig/biconfig/
For information, see Section 6.4.2, "What Are Diagnostic Log Configuration Files
and Where Are They Located?"
2. Locate the section in which you must add the Format element, which specifies the
log file format. The default is ODL-TEXT.
To use the Fusion Middleware Control Log Viewer to view and search through the
log files for Oracle Business Intelligence, then the files must be in either ODL-Text
or ODL-XML format.
3. Include the element and its ancestor elements as appropriate, as shown in the
following example:
<server>
<ServerInstance>
<Log>
<Format>ODL-TEXT</Format>
</Log>
</ServerInstance>
</server>

For an example of a JavaHost Server diagnostic log configuration file, see


Example 62.
4. Save your changes and close the file.
5. Restart Oracle Business Intelligence.

6.3.3 Diagnosing Issues Using the Log Viewer


You can use the Log Viewer in Fusion Middleware Control to find messages that can
assist you in resolving issues with the Oracle Business Intelligence system.
To diagnose issues using the Log Viewer:

Diagnosing and Resolving Issues in Oracle Business Intelligence 6-5


Viewing and Configuring Diagnostic Log Files

1. Display Fusion Middleware Control.


2. In the Navigator, select WebLogic Domain, right-click bi, and select Logs, then
View Log Messages.
The Log Messages page is displayed. The Log Viewer collects lines from all log
files and displays them on this page. You can filter the lines to view the ones in
which you are interested.
3. To start filtering the list, enter search criteria to locate the messages in which you
are interested:
If you know that an error occurred around a certain date, then set the Date
Range to Time Interval. Select the start and end dates for filtering.
If the error happens continually, then set the Date Range to Most Recent.
Select Days and specify a number such as 1 or 3.
For Message Types, select the following: Incident Error, Error, Warning, and
Notification. If the number of messages that is returned is too large, then
deselect Notification to see only errors and warnings.
The advantage of selecting Notification is that you can see what the Oracle
Business Intelligence system was doing, which can assist you in determining
where something went wrong.
4. To filter for the messages for Oracle Business Intelligence
a. Click Add Fields, then select Module, and click Add.
b. Ensure that Module is set to contains, then enter the following value:
oracle.bi.management
That value specifies the name of the Java package from which all log entries
for systems management for Oracle Business Intelligence originate.
5. Click Search.
The page lists all log messages that meet the criteria, including the errors and
warnings that lead up to the problem that you are diagnosing.
6. To save a copy of the log messages, click Export Messages to File, then As Oracle
Diagnostic Log Text (.txt) or other format appropriate to your needs.
As you view the log messages, you can see that the Message column explains what
operations happened at what times. You can learn important information such as
when servers were restarted or a configuration change occurred. You can use the
values in the Log File column to learn which files were written to, which gives a clue
as to what Oracle Business Intelligence was doing. For example, a value of
nqserver.log indicates an interaction with the Oracle BI Server and a value of
sawlog5.log indicates an interaction with Presentation Services.
You can view the log messages to see what might have contributed to a particular
situation. For example, suppose that you make changes in Fusion Middleware Control
to specify a different repository, but you cannot see the repository in Presentation
Services. When you view the log messages, you find an error message that indicates
that the computer that hosts the Managed Server and to which the new repository was
copied has run out of memory. An earlier error message indicates that the
Administration Server had reported the change to the repository and had tried to
synchronize the change to the Managed Server.

6-6 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Understanding Diagnostic Log and Log Configuration Files

6.4 Understanding Diagnostic Log and Log Configuration Files


This section discusses diagnostic log files and diagnostic log configuration files, and
contains the following topics:
Section 6.4.1, "What Are Diagnostic Log Files and Where Are They Located?"
Section 6.4.2, "What Are Diagnostic Log Configuration Files and Where Are They
Located?"
Section 6.4.3, "What Are Log File Message Categories and Levels?"
Section 6.4.4, "What is Log File Rotation?"
Section 6.4.5, "What Messages Are Included in the System Log?"

6.4.1 What Are Diagnostic Log Files and Where Are They Located?
Diagnostic log files are files used to store message information that is generated by
Oracle Business Intelligence servers. These log files are stored in the following
location:
BI_DOMAIN/servers/INSTANCE_KEY/logs (for system components)
BI_DOMAIN/servers/WLS_SERVER_NAME/logs (for JEE components).
For example:
oraclehome/user_projects/domains/bi/servers/obis1/logs (for BI Server)
oraclehome/user_projects/domains/bi/servers/AdminServer/logs (for JEE
Administration server)
The following diagnostic log files are used in Oracle Business Intelligence:
Presentation Services
\CatalogCrawler\sawcatalogcrawlerlogsysn.log The catalog crawler log
file, which is not searchable in the Fusion Middleware Control Log Viewer.
sawlogn.log The Presentation Services log file that represents the latest part
of diagnostic log output and is searchable in the Fusion Middleware Control
Log Viewer.
For more information specifically about Presentation Services logging, see
Section 6.6, "Logging in Oracle BI Presentation Services."
Oracle BI Server
obis<n>_query.log The Oracle BI Server query log, which is not searchable
in the Fusion Middleware Control Log Viewer.
For example, where <n> = -1, -2.
Note: The date and timestamp is in the log file.
nqserver<n>.log The Oracle BI Server main diagnostic log, which is
searchable in the Fusion Middleware Control Log Viewer.
For example, where <n> = 1, 2
Note: The date and timestamp is in the log file.
nqsadmintool.log The log for the Oracle BI Administration Tool.
Oracle BI Server utilities For example, biserverxmlexec and equalizerpds,
also generate their own logs when they are run.

Diagnosing and Resolving Issues in Oracle Business Intelligence 6-7


Understanding Diagnostic Log and Log Configuration Files

JavaHost
jh.log The JavaHost Server main diagnostic log, which is searchable in the
Fusion Middleware Control Log Viewer.
Note: The date and timestamp is in the log file.
Oracle BI Scheduler
nqscheduler.log The Oracle BI Scheduler log file, which is searchable in the
Fusion Middleware Control Log Viewer.
Note: The date and timestamp is in the log file.
Cluster Controller
nqcluster.log The Oracle BI Cluster Controller diagnostic file, which is
searchable in the Fusion Middleware Control Log Viewer.
Note: The date and timestamp is in the log file.
BI JEE log (Action Services and Security Services), both of the following log files
are searchable in the Fusion Middleware Control Log Viewer:
AdminServer-diagnostic.log
bi_server1-diagnostic.log

Note: For the following log files, you cannot set the time zone in
which messages are logged in the files: nqcluster.log, nqscheduler.log,
and nqserver<n>.log. The messages are logged in the files in
Greenwich Mean Time (GMT). When you view the messages in the
Fusion Middleware Control Log Viewer, you see the messages in the
local time zone.

6.4.2 What Are Diagnostic Log Configuration Files and Where Are They Located?
Diagnostic log configuration files control output to diagnostic log files for Oracle
Business Intelligence.

Note: Editing a diagnostic log configuration file for a single


component is not advised, because changes might subsequently be
overwritten.

Log configuration files for Oracle Business Intelligence are stored in the following
locations:
BI_DOMAIN/config/fmwconfig/biconfig/BI_COMPONENT_NAME
For example:
oraclehome/user_projects/domains/bi/config/fmwconfig/biconfig
./OBICCS/ccslogconfig.xml
./OBIJH/logging_config.xml
./OBIPS/instanceconfig.xml
./OBSCH/schedulerconfig.xml
./OBIS/logconfig.xml

6-8 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Understanding Diagnostic Log and Log Configuration Files

About Formats in Diagnostic Log Configuration Files


Diagnostic log configuration files conform to the Oracle Diagnostic Log (ODL)
standard, although they can differ slightly in appearance.
Example 61 and Example 62 illustrate two of the log configuration files for Oracle
Business Intelligence.

Example 61 BI Server Diagnostic Log Configuration File Format


<server>
<ServerInstance>
<Log>
<MaximumFileSizeKb>10000</MaximumFileSizeKb>
<MaximumLogAgeDay>60</MaximumLogAgeDay>
<Format>ODL-TEXT</Format>
<Level>
<IncidentError>1</IncidentError>
<Error>1</Error>
<Warning>16</Warning>
<Notification>1</Notification>
<Trace>16</Trace>
</Level>
</Log>
<UserLog>
<MaximumFileSizeKb>10000</MaximumFileSizeKb>
<MaximumLogAgeDay>10</MaximumLogAgeDay>
<Format>ODL-TEXT</Format>
</UserLog>
</ServerInstance>
</server>

Example 62 JavaHost Server Diagnostic Log Configuration File Format


<?xml version = '1.0' encoding = 'utf-8'?>
<logging_configuration>
<log_handlers>
<log_handler name='odl-handler'
class='oracle.core.ojdl.logging.ODLHandlerFactory'>
<property name='path' value='C:\oracle_bi_ee_
BIFNDNPTPSNT0911060426S-Release\jhlogs\javahost.log'/>
<property name='maxFileSize' value='1000000'/>
<property name='maxLogSize' value='5000000'/>
</log_handler>
</log_handlers>
<loggers>
<logger name='saw' level='NOTIFICATION:1' useParentHandlers='false'>
<handler name='odl-handler'/>
</logger>
</loggers>
</logging_configuration>

Oracle Business Intelligence components control their diagnostic log files by using
server-specific settings in their log configuration files, for example:
Oracle BI Presentation Services log configuration file:
- writerClassId settings configure messages that the system writes to the
sawlog.log file.
Oracle BI Server log configuration file:

Diagnosing and Resolving Issues in Oracle Business Intelligence 6-9


Understanding Diagnostic Log and Log Configuration Files

- Log settings configure messages that the system writes to the nqserver.log file.
For more information, see Section 6.4.5, "What Messages Are Included in the
System Log?"
- UserLog settings configure messages that the system writes to the nqquery.log
file.
For more information, see Section 6.5, "Managing the Query Log."
Oracle BI Scheduler log configuration file:
- Log settings configure messages that the system writes to the nqscheduler.log file.
JavaHost Server log configuration file:
- log_handlers elements and subelements enable configuration of the log file
rotation policy and the specification of the log file name and its location.
- loggers elements and subelements enable appropriate handling of Java
component (JavaHost Server) log levels, by mapping the JavaHost Server log
levels to the standard Oracle Diagnostic Log (ODL) log levels.

6.4.3 What Are Log File Message Categories and Levels?


Categories and levels for log file messages define the detail and level of importance
with which the system writes messages to a log file. Fusion Middleware Control
enables you to control these settings in the logconfig.xml file.
Each message category in a log file for Oracle Business Intelligence is set to a specific
default value between 1 and 32, and only messages with a level less than or equal to
the log level is logged.
Log file message categories are described in Table 62.

Table 62 Log File Message Category Levels


Category:Level Description
IncidentError:1 A serious problem caused by unknown reasons has occurred. You can fix
the problem only by contacting Oracle Support Services.
No performance impact.
Error:1 A problem that requires attention from the system administrator has
occurred.
No performance impact.
Warning:1 An action occurred or a condition was discovered that must be reviewed
and might require action before an error occurs.
No performance impact.
Notification:1 A report of a normal action or event has occurred. This could be a user
operation, such as "login completed" or an automatic operation such as a
log file rotation.
No performance impact.
Notification:16 A configuration-related message or problem has occurred.
Low performance impact. You can enable this level broadly in a
production environment without having a significant performance impact
in the software.

6-10 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Understanding Diagnostic Log and Log Configuration Files

Table 62 (Cont.) Log File Message Category Levels


Category:Level Description
Trace:1 A trace or debug message that is used for debugging or performance
monitoring has been written. Typically this message contains detailed
event data that is clear enough to be understood by someone who does
not know internal implementation details.
Small performance impact. This level might be enabled broadly
occasionally on a production environment to debug issues with the
software. Enabling logging at this level might have a small performance
impact, but not to the point of making the software unusable.
Trace:16 A fairly detailed trace or debug message has been written. The message is
clear enough to be understood by Oracle Support Services engineers who
have a deep knowledge of the product but might not know full details of
the internal implementation.
High performance impact. This level must not be enabled on a production
environment, except on special situations to debug issues with the
software.
Trace:32 A highly detailed trace or debug message has been written. The message
is intended for an Oracle developer working on the software who knows
enough details about the implementation of the subsystem that generates
the message.
Very high performance impact. This level is not expected to be enabled in
a production environment and developers use it only to debug the
software on a test or development environment.

In the following log configuration file example, in the Notification message category,
only level 1 messages are logged. If the log level is set to 0, then nothing is logged for
that message category.
<Level>
<IncidentError>1</IncidentError>
<Error>1</Error>
<Warning>1</Warning>
<Notification>1</Notification>
<Trace>1</Trace>
</Level>

Avoid manually changing the default settings in the log file. Use Fusion Middleware
Control to make changes. For more information, see Section 6.3.2.1, "Using Fusion
Middleware Control to Configure Log File Rotation Policy and Specify Log Levels."

6.4.4 What is Log File Rotation?


Log file rotation is the creation of new log files, when the file exceeds a specified
threshold or date. Take the MaximumFileSizeKb setting for the component log
configuration file for the Oracle BI Scheduler as an example. Whenever a log file
exceeds the size that is specified by this setting, then the existing Scheduler log file is
renamed, and a new log file is created. Additionally, a log file date that is older than
the MaximumLogAgeDay setting is deleted.
Different Oracle BI components have different log file names, and different settings
within their log configuration files. For example, the file naming convention for the
Scheduler is as follows:
nqscheduler.log The latest log file.
nqscheduler-<n>.log The renamed previous log file.

Diagnosing and Resolving Issues in Oracle Business Intelligence 6-11


Managing the Query Log

where <n> = date and timestamp, for example nqscheduler-20100909-2135.log


For more information, see Section 6.3.2.1, "Using Fusion Middleware Control to
Configure Log File Rotation Policy and Specify Log Levels."

6.4.5 What Messages Are Included in the System Log?


The Oracle BI Server writes messages to the nqserver.log file, based on configuration
settings. In addition to writing messages to this log file, the BI Server writes certain
severe messages to the system log file for UNIX systems. The following list includes
the kinds of messages that the BI Server writes to the system log file:
When the BI Server cannot start (for example, because another server has
previously started), then the system log file includes a message such as the
following one:
Another server is already running on : @1%ls and port: @2%ls.
When memory problems occur, the system log file includes a message such as the
following one:
Could not enable the Low-Fragmentation Heap.
When the hard disk on the computer is full, the system log file includes a message
such as the following one:
Out of disk space.

6.5 Managing the Query Log


The Oracle BI Server provides a facility for logging query activity at the individual
user level. Use logging for quality assurance testing, debugging, and troubleshooting
by Oracle Support Services. In production mode, query logging is typically disabled.
The query log file is named nqquery.log, and is located in:
BI_DOMAIN/servers/obisn/logs
Oracle BI Server query logging is tracked at a user level. It is a resource-intensive
process if you track the entire user community.

Note: For production systems, it is recommended that query logging


be enabled only for a very targeted user community. In production
systems, you can use usage tracking as the production-level logging
facility. See Chapter 7, "Managing Usage Tracking" for more
information.

It is recommended that you test users only when the user name clearly indicates it is a
test user and have verified that query logging is enabled. If logging is enabled for such
users, then it is recommended that they be given names such as sales_admin_with_
logging, sales_dev_with_logging, or sales_test_with_logging, so that you can readily
identify them. Even production administrator logins should not have query logging
enabled, because it strains the available resources.
Also disable query logging for the following:
The SQL statement in the initialization string. The Initialization string field is in
the Initialization Block dialog, in the General tab.
The LOGGING column references stored values for the log level.

6-12 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Managing the Query Log

Set the logging level to 0 (zero) for each production user. The Logging level field is
in the User dialog, in the User tab. In the Administration Tool, select Identity from
the Manage option on the main toolbar. In the Identity Manager dialog,
double-click a user and select the User tab.
This section contains the following topics:
Section 6.5.1, "Configuring Query Logging"
Section 6.5.2, "Using the Log Viewer"

6.5.1 Configuring Query Logging


This section includes information about setting the size of the query log, choosing a
logging level, and enabling query logging for a user.
Because query logging can produce very large log files, the logging system is turned
off by default. You can enable logging to test that the repository is configured properly,
to monitor activity on the system, to help solve performance problems, or to assist
Oracle Support Services. You must enable query logging on the system for each user
whose queries you want logged. You do this using the Oracle BI Administration Tool.

6.5.1.1 Setting the Query Logging Level


You can enable query logging levels for individual users, as described in
Section 6.5.1.2, "Setting the Query Logging Level for a User." You cannot configure a
logging level for a group.
A session variable overrides the logging level for a particular user. For example, if the
administrator has a logging level of 4 and the session variable logging level is defined
as the default 0 (zero) in the repository, then the logging level for the administrator is
0.
Set the logging level based on the amount of logging that is appropriate for your
organization. In normal operations, logging is generally disabled (that is, the logging
level is set to 0). If you decide to enable logging, then select a logging level of 1 or 2.
These two levels are designed for use by administrators.
You might want to diagnose performance or data issues by setting a temporary log
level for a query. You can enable query logging for a select statement by adding a
prefix clause in the Advanced SQL Clauses section of the Advanced tab in Oracle BI
Presentation Services. For example, for the select statement:
SELECT year, product, sum(revenue) FROM time, products, facts;

You can specify the logging level of 5 in the Prefix field as follows:
Set Variable LOGLEVEL=5;

For this query, the logging level of 5 is used regardless of the value of the underlying
LOGLEVEL variable.

Note: Use logging levels greater than 2 only with the assistance of
Oracle Support Services.

The query logging levels are described in Table 63.

Diagnosing and Resolving Issues in Oracle Business Intelligence 6-13


Managing the Query Log

Table 63 Query Logging Levels


Logging Level Information That Is Logged
Level 0 No logging.
Level 1 Logs the SQL statement issued from the client application. Also logs the
following:
Physical query response time The time for a query to be processed
in the back-end database.
Number of physical queries The number of queries that are
processed by the back-end database.
Cumulative time The sum of time for all physical queries for a
request (that is, the sum of all back-end database processing times and
DB-connect times).
DB-Connect time The time taken to connect to the back-end
database.
Query cache processing The time taken to process the logical query
from the cache.
Elapsed time The time that has elapsed from when the logical query
is presented to the BI Server until the result is returned to the user.
Elapsed time can never be less than response time, because elapsed
time takes into account the small extra time between the logical query
being presented to the BI Server to the start of preparation of the
query. In cases where this difference in time is negligible, the elapsed
time equals the response time.
Response time The time taken for the logical query to prepare,
execute, and fetch the last record. This matches the TOTAL_TIME_SEC
that is logged in usage tracking, as described in Section 7.3,
"Description of the Usage Tracking Data."
Compilation time The time taken to compile the logical query.
For each query, logs the query status (success, failure, termination, or
timeout), and the user ID, session ID, and request ID.
Total Time in BI Server the time spent in the BI Server for query
execution only (that is, not compilation time).
Level 2 Logs everything logged in Level 1.
Additionally, for each query, logs the repository name, business model
name, subject area name, SQL statement issued against the physical
database, queries issued against the cache, number of rows returned from
each query against a physical database and from queries issued against the
cache, and the number of rows returned to the client application.
Level 3 Logs everything logged in Level 2.
Additionally, adds a log entry for the logical query plan, when a query that
was supposed to seed the cache was not inserted into the cache, when
existing cache entries are purged to make room for the current query, and
when the attempt to update the exact match hit detector fails.
Do not select this level without the assistance of Oracle Support Services.
Level 4 Logs everything logged in Level 3.
Additionally, logs the query execution plan. Do not select this level without
the assistance of Oracle Support Services.
Level 5 Logs everything logged in Level 4.
Additionally, logs intermediate row counts at various points in the
execution plan. Do not select this level without the assistance of Oracle
Support Services.
Level 6 and 7 Not used.

6-14 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Managing the Query Log

6.5.1.2 Setting the Query Logging Level for a User


To set the query logging level for a user:
1. In the Oracle BI Administration Tool, select Manage, then Identity.
The Identity Manager dialog is displayed.
2. Double-click the name of the user for which you want to set the query logging
level.
The User dialog is displayed.
3. Set the logging level by clicking the Up or Down arrows next to the Logging Level
field.
To disable query logging for a user, set the logging level to 0.
4. Click OK.

6.5.2 Using the Log Viewer


Use the Oracle Business Intelligence Log Viewer utility (or a text editor) to view the
query log. Each entry in the query log is tagged with the name of the user who issued
the query, the session ID of the session in which the query was initiated, and the
request ID of the individual query.

6.5.2.1 Running the Log Viewer Utility


To run the Log Viewer utility (located on UNIX in ORACLE_
HOME/bi/bifoundation/server/bin), open a command prompt, and enter
nqlogviewer with any combination of its arguments. The syntax is as follows:
nqlogviewer [-u user_name] [-f log_input_filename]
[-o output_result_filename]
[-s session_ID] [-r request_ID]

In this syntax:
user_name is the name of a user in the Oracle Business Intelligence repository. This
parameter limits the scope to entries for a particular user. If not specified, all users
for whom query logging is enabled are displayed.
log_input_filename is the name of an existing log file from where the content is
taken. This parameter is required.
output_result_filename is the name of a file in which to store the output of the
log. If the file exists, then the results are appended to the file. If the file does not
exist, then a new file is created. If this argument is not specified, then output is
sent to the monitor screen.
session_ID is the session ID of the user session. The BI Server assigns each session
a unique ID when the session is initiated. This parameter limits the scope of the
log entries to the specified session ID. If not specified, then all session IDs are
displayed.
request_ID is the request ID of an individual query. The BI Server assigns each
query a unique ID when the query is initiated. This parameter limits the scope of
the log entries to the specified request ID. If not specified, then all request IDs are
displayed.
The request ID is unique among the active requests, but not necessarily unique
during the session. Request IDs are generated in a circular manner, and if a request
is closed or if the session is long enough, then a request ID is reused.

Diagnosing and Resolving Issues in Oracle Business Intelligence 6-15


Logging in Oracle BI Presentation Services

You can also locate user names, session IDs, and request IDs through the Session
Manager. See Oracle Fusion Middleware Security Guide for Oracle Business Intelligence
Enterprise Edition for information.
Administrators can view the query log using the Manage Sessions option in the
Presentation Services Administration page.

6.5.2.2 Interpreting the Log Records


After you have logged some query information and started the log viewer, you can
analyze the log. Log entries for levels 1 and 2 are generally self-explanatory. The log
entries can provide insights to help database administrators (DBAs) in charge of the
underlying databases tune them for optimum query performance. The query log can
also help you check the accuracy of applications that use the BI Server.
The log is divided into the following sections:
SQL Request This section lists the SQL statement that is issued from the client
application. You can use this information to rerun the query from the same
application, or from a different application.
General Query Information This section lists the repository, the business
model, and the subject area from which the query was run. You can use this
information to provide statistics on query usage that you can use to set priorities
for future application development and system management.
Database Query This section begins with an entry that reads "Sending query to
the database named <data_source_name>," where <data_source_name> is the name
of the data source to which the BI Server is connecting. Multiple database queries
can be sent to one or more data sources. Each query has an entry in the log.
The database query section has several uses, such as recording the SQL statement
that was sent to the underlying databases. You can use this logged SQL statement
to run queries directly against the database for performance tuning, results
verification, or other testing purposes. You can also use this information to
examine the tables that are being queried to verify that aggregate navigation is
working as you expect. If you understand the structure of the underlying
database, then it might also provide some insights into potential performance
improvements, such as useful aggregate tables or indexes to build.
Query Status The query success entry in the log indicates whether the query
completed successfully, or failed. You can search through the log for failed queries
to determine why they failed. For example, all the queries during a particular time
period might have failed due to database downtime.

6.6 Logging in Oracle BI Presentation Services


This section describes logging specifically in Presentation Services and contains the
following topics:
Section 6.6.1, "Using the Oracle BI Presentation Services Logging Facility"
Section 6.6.2, "Setting the Logging Levels for Oracle BI Presentation Services"
Section 6.6.3, "Structure for the Oracle BI Presentation Services Configuration File"
Section 6.6.4, "Examples of the Formats of Logged Messages"
Section 6.6.5, "Oracle BI Presentation Services Message Structure"
Section 6.6.6, "Oracle BI Presentation Services Log Filters"

6-16 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Logging in Oracle BI Presentation Services

Section 6.6.7, "Diagnosing Issues with Agents"


For general information about logging in Oracle Business Intelligence, see Section 6.4,
"Understanding Diagnostic Log and Log Configuration Files."

6.6.1 Using the Oracle BI Presentation Services Logging Facility


By default, Oracle BI Presentation Services is configured to log all error events and
informational and warning events of sufficient importance. An example of an
important informational event is a server starting up or a server shutting down. Log
files are named sawlogxx.log, where the xx is replaced by an incremented number.
To debug specific issues that a user might be encountering, the logging level can be
increased to log more information than the default configuration. For example, while
debugging a particular Oracle BI Presentation Services connectivity issue, you can
increase the maximum logging on the saw.odbc log source only. This adds detailed
logging for that component, without cluttering the log with detailed logging from
other events. All Oracle BI Presentation Services configuration information is loaded
from the instanceconfig.xml file.

Caution: Because logging affects performance, do not increase the


logging on a production implementation, except to diagnose specific
issues.

6.6.2 Setting the Logging Levels for Oracle BI Presentation Services


You use options on the Administration page in Presentation Services to affect logging
levels.
To set logging levels for Presentation Services:
1. In the global header, click Administration.
2. In the Maintenance and Troubleshooting area, select the logging level to use under
Reload Log Configuration.
3. Click Reload Log Configuration to allow the change to take effect without
restarting Presentation Services.
The change remains in effect even when you stop and restart Presentation
Services.
4. Click the Manage Sessions link to display the Manage Sessions page.
5. For each session, specify the appropriate level in the Log Level column of the
table.
The updated level takes effect immediately for that session. When you select a
level, ensure that its severity value is smaller than or equal to the value specified
for all messages in Presentation Services.

6.6.3 Structure for the Oracle BI Presentation Services Configuration File


The structure of the configuration file is shown in Example 63. The cardinality of each
node is shown in brackets.

Example 63 Structure of Log Section in instanceconfig.xml File


Logging [1..1]
Writers [0..1]

Diagnosing and Resolving Issues in Oracle Business Intelligence 6-17


Logging in Oracle BI Presentation Services

Writer [0..1]
WriterClassGroups [0..1]
Filters [0..1]
FilterRecord [0..n]

An example of an instanceconfig.xml file that has four writers is shown in


Example 64.

Example 64 instanceconfig.xml File with Four Writers


<?xml version="1.0" ?>
<Server>
. . . . . . .
<Logging>
<Writers>
<Writer implementation="FileLogWriter" name="Global File Logger"
writerClassId="1" dir="{%ORACLE_BIPS_INSTANCE_LOGDIR%}" filePrefix="sawlog"
maxFileSizeKb="10000" filesN="10" fmtName="ODL-Text" ODLLogFilePath="{%ORACLE_
BIPS_INSTANCE_LOGDIR%}/diagnostic.log"/>
<Writer implementation="CoutWriter" name="Global Output Logger"
writerClassId="2" />
<Writer implementation="EventLogWriter" name="Event Logger"
writerClassId="3" />
<Writer implementation="CrashWriter" name="CrashWriter"
writerClassId="4"
/>
</Writers>
<WriterClassGroups>
<WriterClassGroup name="All">1,2,3,4</WriterClassGroup>
<WriterClassGroup name="File">1</WriterClassGroup>
<WriterClassGroup name="Console">2</WriterClassGroup>
<WriterClassGroup name="EventLog">3</WriterClassGroup>
<WriterClassGroup name="Crash">4</WriterClassGroup>
</WriterClassGroups>
<Filters>
<FilterRecord writerClassGroup="Console" path = "saw" information="1" warning="31"
error="31" trace="0" incident_error="32" />
<FilterRecord writerClassGroup="File" path = "saw" information="1" warning="31"
error="31" trace="0" incident_error="32" />
<FilterRecord writerClassGroup="File" path="saw.mktgsqlsubsystem.joblog"
information="1" warning="2" error="31" trace="0" incident_error="32"/>
<FilterRecord writerClassGroup="File" path="saw.httpserver.request"
information="16" warning="32" error="32" trace="0" incident_error="32"/>
<FilterRecord writerClassGroup="File" path="saw.httpserver.response"
information="16" warning="32" error="32" trace="0" incident_error="32"/>
</Filters>
</Logging>
</Server>

Table 64 contains a description of each node in the configuration hierarchy.

Table 64 Oracle BI Presentation Services Log Configuration File Elements


Element Attribute Description
Writers None Contains writers configuration.
This configuration is loaded on startup.
Writer None Configures a writer.

6-18 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Logging in Oracle BI Presentation Services

Table 64 (Cont.) Oracle BI Presentation Services Log Configuration File Elements


Element Attribute Description
Writer disableCentralContro (Optional) Determines that this entry is not
l updated by Fusion Middleware Control.
Default value is true.
Writer implementation The following implementations are defined:
FileLogWriter. Writes to a disk file.
CoutWriter. Writes to standard output.
EventLogWriter. Writes to a Windows
event log or UNIX syslog.
CrashWriter. A Windows only facility that
writes to a crash dump file when
Presentation Services attempts to log from
a specific source file and line number.
Used in a production environment for
information of some loggable but
irrecoverable error (for example, failed
NQTEST).
Note: Use this implementation with care
as it might leave the server in an unstable
state. Use this implementation in very rare
diagnostic-only scenarios on a test system.
On Windows, CrashWriter requires the
appropriate version of dbghelp.dll (at
least 6.0.17.0).
The correct dbghelp.dll can be found in
support/windows/system64.
Put this DLL in the WINNT/system64 or in
the main/bin directory.
No registration is required.
Writer name Unique name for the writer.
Writer writerClassId Specifies an integer number in the range 1
through 10. This number is used by filters to
allow or prohibit logging.
Each distinct writer must have a unique value,
which is used later for filter configuration.
Different writers might have the same class ID,
but if they do, those writers cannot be
distinguished by filters.
Writer fmtName (Optional) Specifies the format of logged
messages. Valid values are:
default - 10g style. Formats messages
with identifying headings.
ODL-TEXT. Formats messages in Oracle
Diagnostic Text format.
ODL-XML. Formats messages in Oracle
Diagnostic XML format.
If you do not set this attribute, then logged
messages are displayed in the default format
which for file log writers is 10g style and for
console is ODL-TEXT.
See Section 6.6.4, "Examples of the Formats of
Logged Messages" for examples.

Diagnosing and Resolving Issues in Oracle Business Intelligence 6-19


Logging in Oracle BI Presentation Services

Table 64 (Cont.) Oracle BI Presentation Services Log Configuration File Elements


Element Attribute Description
Writer (FileLogWriter dir Specifies the directory where log files are
specific attribute) created.
Writer (FileLogWriter ODLLogFilePath Specifies the file that Fusion Middleware
specific attribute) Control displays in the Log Viewer.
Writer (FileLogWriter maxFileSizeKb Specifies the maximum size of the logging file
specific attribute) in kilobytes.
When the file size limit is reached, the file is
closed and a new logging file is created.
Writer (FileLogWriter filePrefix Specifies the prefix for log files.
specific attribute)
Writer (FileLogWriter filesN Specifies the maximum number of logging
specific attribute) files.
When this number is exceeded, the first file is
deleted and re-created again. Then the logger
starts to write to the beginning of the first file.
Writer winSource Specifies the event log source for logged
(EventLogWriter events.
specific attribute)
Writer (CrashWriter file Specifies the dump file path.
specific attribute)
On Windows, a dump file is created in
bin/coredumps and Presentation Services
continues to run.
Writer (CrashWriter line Dump file line number.
specific attribute)
WriterClassGroups None Contains the definition for writer classes. A
writer class is a group of writer class IDs.
WriterClassGroup name Specifies the name of the WriterClassGroup.
(Contains [as child
text] a
comma-delimited list
of class IDs.)
Filters None Contains filter configuration.
FilterRecord writerClassGroup Specifies the group of writers to which this
record is applied. WriterClassGroup is likely
defined previously in the WriterClassGroups
section.
FilterRecord disableCentralContro (Optional) Determines that this entry is not
l updated by Fusion Middleware Control.
Default value is true.
FilterRecord path Specifies the log source path. To enable the
logging of SOAP information, enter the
following value:
saw.httpserver.request.soaprequest
The current filter record is applied to the
software component that is identified by that
path and all its subcomponents.
FilterRecord information Contains an integer that specifies the severity
of the corresponding message type.
Only messages with a severity index less than
the provided number are logged.

6-20 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Logging in Oracle BI Presentation Services

Table 64 (Cont.) Oracle BI Presentation Services Log Configuration File Elements


Element Attribute Description
FilterRecord warning Contains an integer that specifies the severity
of the corresponding message type.
Only messages with a severity index less than
the provided number are logged.
FilterRecord error Contains an integer that specifies the severity
of the corresponding message type.
Only messages with a severity index less than
the provided number are logged.
FilterRecord trace Contains an integer that specifies the severity
of the corresponding message type.
Only messages with a severity index less than
the provided number are logged.
FilterRecord incident_error Contains an integer that specifies the severity
of the corresponding message type.
Only messages with a severity index less than
the provided number are logged.

6.6.4 Examples of the Formats of Logged Messages


The fmtName attribute of the Writer element formats logged messages in one of three
formats: default (10g style), ODL-TEXT, and ODL-XML. The following entries are
examples of these formats.
Example 65 shows the default format.

Example 65 Default Format


The default format generates messages with identifying headings, such as:
Type: Information
Severity: 30
Time: Wed Jul 26 11:22:20 2006
File: project\sawserver\sawserver.cpp
Line: 399
Properties: ThreadID-2552
Location:
saw.sawserver
saw.sawserver.initializesawserver
saw.sawserver
Oracle BI Presentation Services has started successfully.

Example 66 shows the ODL-TEXT format.

Example 66 ODL-TEXT Format


The short format generates messages in a shortened form without identifying
headings, such as:
[timestamp] [component id] [messagetype:level] [message-id] [module id]
([field-name: field-value])* message-text [[
supplemental-detail
]]

[2010-05-27T10:51:20.000-07:00] [OBIPS] [NOTIFICATION:1] [] [saw.sawserver] [ecid:


1243446680218334471555761] [tid: 2552] Oracle BI Presentation Services (OBIPS)

Diagnosing and Resolving Issues in Oracle Business Intelligence 6-21


Logging in Oracle BI Presentation Services

11.1.1.2 (Build 0) are starting up.[[


File:sawserver.cpp
Line:432
Location:
saw.sawserver
saw.sawserver.initializesawserver
saw.sawserver
ecid: 1243446680218334471555761
]]
Example 67 shows the ODL-XML format.

Example 67 ODL-XML Format


The xml format generates messages in XML format, such as:
<msg time="2010-05-08T18:41:05.000+00:00"
comp_id="OBIPS" type="NOTIFICATION" level="1" msg_id=""
module="saw.sawserver" ecid="124180446517874242628761" tid="127c">
<txt> Oracle BI Presentation Services has started successfully</txt>
<suppl_detail />
</msg>

6.6.5 Oracle BI Presentation Services Message Structure


Each message that is logged by Presentation Services has several components, as
described in Table 65.

Table 65 Components of Presentation Services Log Message


Message Component Description
Message Text The text of the log message to the user.
Message Type One of five types: information, warning, error, incident_error or
trace.
For information, see Table 62.
Severity The severity is represented as a positive integer.
The lower the value, the more important the message. A
message with severity of 0 is the most important type of
message, whereas a message with a severity of 32 is not
important at all.
Message Properties Properties indicate other kinds of information. The kind varies
among messages and might include user name, the IP address
of the client browser, the thread ID, and so on.

6.6.6 Oracle BI Presentation Services Log Filters


FilterRecords customize logging details. Use FilterRecords to specify the
implementation (output type) and logging levels for categories of web logs: Incident
Error, Error, Trace, Warnings, and Information.
In the following example, the first two FilterRecords contain the following string:
path="saw"

This string logs the informational events at level 1, the error messages at level 31, and
so on:
<FilterRecord writerClassGroup="Console" path="saw" information="1" warning="31"
error="31" trace="0" incident_error="32" />

6-22 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Logging in Oracle BI Presentation Services

<FilterRecord writerClassGroup="File" path="saw" information="1" warning="31"


error="31" trace="0" incident_error="32" />
<FilterRecord writerClassGroup="File" path="saw.mktgsqlsubsystem.joblog"
information="1" warning="2" error="31" trace="0" incident_error="32"/>

This high-level path applies to every event.


You can customize FilterRecords by adding new FilterRecords, such as the third one
shown in the preceding example, with finer-grain specification of log levels for events
of various types. In this example, information is being logged to a disk file from
saw.mktgsqlsubsystem.log, which generates Marketing job events.
You can disable logging of job details by changing the information level from 1 to 0, as
shown in the following example, or by commenting out the lines:
<FilterRecord writerClassGroup="Console" path="saw" information="1" warning="31"
error="31" trace="0" incident_error="32" />
<FilterRecord writerClassGroup="File" path="saw" information="1" warning="31"
error="31" trace="0" incident_error="32" />
<FilterRecord writerClassGroup="File" path="saw.mktgsqlsubsystem.joblog"
information="1" warning="2" error="31" trace="0" incident_error="32"/>

6.6.7 Diagnosing Issues with Agents


This section contains the following topics:
"Debugging Agents Using Fusion Middleware Control"
"Manually Debugging Agents Using instanceconfig.xml"

6.6.7.1 Debugging Agents Using Fusion Middleware Control


Agent error and debug log entries are written to the main scheduler log file
nqscheduler.log, and are visible in Log Viewer using Fusion Middleware Control. For
more information, see Section 6.3.1, "Using Fusion Middleware Control to View Log
Information, Error Messages, and Alerts".
An agent log entry includes key agent events, and provides information on a single
trace line. For example:
Agent Chain Completed. Status: Completed, Agent ID:
/users/weblogic/ChainedAgent, UserID: weblogic, OBIPS: example.com:0:9710,
Job/Instance ID: 123/4567.
Table 66 details agent event logging, and associated trace types and levels.

Table 66 Agent Event Logging and Associated Values


Event State Message Type:Level
Agent Chain Started Running TRACE:1
Agent Chain Started ReRunning NOTIFICATION:1
Agent Chain Complete Failed ERROR:1
Agent Chain Complete Timed Out ERROR:1
Agent Chain Complete Timed Out WARNING:1
Agent Chain Complete Warning WARNING:1
Agent Chain Complete Cancelled NOTIFICATION:1
Agent Chain Complete Try Again NOTIFICATION:1

Diagnosing and Resolving Issues in Oracle Business Intelligence 6-23


Logging in Oracle BI Presentation Services

Table 66 (Cont.) Agent Event Logging and Associated Values


Event State Message Type:Level
Agent Chain Complete Completed TRACE:1
Agent Started N/A TRACE:1
Agent Finished N/A TRACE:1

You can determine the log output detail written to the nqscheduler.log file by setting
the level in Fusion Middleware Control. For more information, see Section 6.3.2,
"Configuring Log File Rotation Policy and Specifying Log Levels". You can also filter
log entries using ECID to find information specific to a particular agent chain.

6.6.7.2 Manually Debugging Agents Using instanceconfig.xml


If an agent fails to execute fully or if debugging is turned on in Oracle BI Scheduler,
then a log file is generated for the agent.
You manually enable debugging by setting the Debug element to true in the Oracle BI
Scheduler instanceconfig.xml file. For example, located at:
oraclehome/user_projects/domains/bi/config/fmwconfig/biconfig/OBISCH
For information, see Section 6.4.2, "What Are Diagnostic Log Configuration Files and
Where Are They Located?"
The location for agent log files is also specified in the instanceconfig.xml file for the
Oracle BI Scheduler (for information, see Section 18.3.3.3, "Agent Scheduler
Configuration Settings.") The default location for log files is the Log directory in the
Oracle Business Intelligence installation directory on the computer where the Oracle BI
Scheduler is installed.
The log file name has the following format:
Agent-JobID-InstanceID.xxx
In this file name:
Agent is the prefix for all agent log files.
JobID is the Oracle BI Scheduler job identifier for the agent.
InstanceID is the Oracle BI Scheduler instance identifier for the agent.
xxx is the file extension:
.err for agent error log files.
.log for debug log files.
The agent error and debug log files are written as separate files for each agent instance
that fails to execute. You can use a text editor to view the files. Entries are generally
self-explanatory.
The presence of an error log does not necessarily mean that an agent failed completely.
For example, suppose an agent delivers content to multiple email addresses. If some
addresses are invalid or the mail server is down, then an error log is generated for the
agent.
You can also view error messages and exit codes for job instances in Job Manager. For
information, see "Instance Properties in Job Manager" in Oracle Fusion Middleware
Scheduling Jobs Guide for Oracle Business Intelligence Enterprise Edition). Exit status shows
the number of deliveries successfully completed.

6-24 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Using ODBC/JDBC Procedures to Obtain Oracle BI Server Diagnostics

6.7 Using ODBC/JDBC Procedures to Obtain Oracle BI Server


Diagnostics
This section describes how to use ODBC/JDBC procedures to obtain diagnostic
information for the Oracle BI Server. It contains the following topics:
Section 6.7.1, "About the Oracle BI Server ODBC/JDBC Procedures"
Section 6.7.2, "Obtaining a List of Available Diagnostic Categories"
Section 6.7.3, "Running Specific Diagnostics"
Section 6.7.4, "About Parameters for ODBC/JDBC Procedures"

6.7.1 About the Oracle BI Server ODBC/JDBC Procedures


You can use ODBC/JDBC procedures to obtain diagnostic information for the Oracle
BI Server. These procedures are especially useful on non-Windows platforms where
you cannot run the Administration Tool.
Use the nqcmd utility to run the procedures using ODBC. See "Using nqcmd to Test
and Refine the Repository" in Oracle Fusion Middleware Metadata Repository Builder's
Guide for Oracle Business Intelligence Enterprise Edition for more information about
nqcmd.
You can also run the procedures using JDBC. For more information about using JDBC
to connect to the Oracle BI Server, see the README.TXT file contained in the bijdbc.jar
file in ORACLE_HOME/bi/bifoundation/jdbc.

6.7.2 Obtaining a List of Available Diagnostic Categories


You can first run OBISAvailableDiagnostics() to get a list and description of the
diagnostic categories that are available. For example:
call OBISAvailableDiagnostics()

The results appear similar to the following:

Category Description
General General overview of the OBIS instance you are connected to.
DBInstance:DBNAME1 All of the statistics related to the DB instance named in
DBNAME1
DBInstance:DBNAMEn All of the statistics related to the DB instance named in
DBNAMEn
LDAP:Instance1 All of the statistics related to the LDAP instance named in
Instance1
LDAP:Instancen All of the statistics related to the LDAP instance named in
Instancen
DBConnectionPool:Instance1 All of the statistics related to the DB connection pool named
in Instance1
DBConnectionPool:Instancen All of the statistics related to the DB connection pool named
in Instancen
ThreadPool:Instance1 All of the statistics related to the Thread pool named in
Instance1
ThreadPool:Instancen All of the statistics related to the Thread pool named in
Instancen

Diagnosing and Resolving Issues in Oracle Business Intelligence 6-25


Using ODBC/JDBC Procedures to Obtain Oracle BI Server Diagnostics

Category Description
Cache:Instance1 All of the statistics related to the Cache named in Instance1
Cache:Instancen All of the statistics related to the Cache named in Instancen

All categories, except for the General category, are Instance categories. Instance
categories are statistics related to a particular instance object (like a specific physical
database). If multiple instances of an object are initialized, separate categories exist for
each instance, in the format category_name:instance_name. See the preceding table for
examples.
Note the following about the ODBC/JDBC categories:
The ThreadPool category only displays statistics from threads created and
managed by the DbConnection PoolMgr.
The Cache category displays statistics from the Compiler Cache and the LDAP
Internal Cache.

6.7.3 Running Specific Diagnostics


After you obtain the available diagnostic categories, you can call
OBISDiagnostics(string) to obtain diagnostics for individual categories, where
string is a category name. For example:
call OBISDiagnostics('ThreadPool:orcldb_pool')

The results appear similar to the following:

Parameter Name Value


CAPACITY 1000
THREAD COUNT 20
BUSY THREAD COUNT 15
ACCUMULATED REQUESTS 5
MAX STACK SIZE 100

The spelling of the category must be correct, or no rows are returned.


Another example might be:
call OBISDiagnostics('General')

The results appear similar to the following:

Parameter Name Value


TOTAL SESSIONS 10
QUERIES PER SEC 5
NEW LOGINS 10
ACTIVE LOGINS 7
NEW REQUESTS 30
DATA CACHE HIT PER SEC 5

6-26 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Using ODBC/JDBC Procedures to Obtain Oracle BI Server Diagnostics

Parameter Name Value


NEW INIT BLOCKS 10

6.7.4 About Parameters for ODBC/JDBC Procedures


The following tables provide parameter reference information for each category type:
Table 67, " General Category Parameters"
Table 68, " DBInstance Category Parameters"
Table 69, " LDAP Category Parameters"
Table 610, " DBConnectionPool Category Parameters"
Table 611, " ThreadPool Category Parameters"
Table 612, " Cache Category Parameters"

Table 67 General Category Parameters


Parameter Name Description
TOTAL SESSIONS The total number of sessions connecting clients to the Oracle BI
Server.
QUERIES PER SEC The number of queries completed each second by the Oracle BI
Server.
NEW LOGINS The total number of new login requests received by the Oracle
BI Server.
ACTIVE LOGINS The total number of active logins within the Oracle BI Server.
NEW REQUESTS The number of new execute requests received by the Oracle BI
Server.
DATA CACHE HIT PER The percentage of data cache hits for each second.
SEC
NEW INIT BLOCKS The total number of new initialization block requests received
by the Oracle BI Server.

Table 68 DBInstance Category Parameters


Parameter Name Description
QUERIES PER SEC The number of queries completed each second by the back-end
database.
FAILED QUERIES PER SEC The number of queries that failed each second in the back-end
database.
NEW PREPARES The number of prepares sent to the back-end database.
ROWS PER SEC The number of rows retrieved each second from the back-end
database.
KB PER SEC The number of kilobytes retrieved each second from the
back-end database.

Table 69 LDAP Category Parameters


Parameter Name Description
NEW REQUESTS The total number of new LDAP authentication requests
received.

Diagnosing and Resolving Issues in Oracle Business Intelligence 6-27


Using ODBC/JDBC Procedures to Obtain Oracle BI Server Diagnostics

Table 69 (Cont.) LDAP Category Parameters


Parameter Name Description
NEW IMPERSONATED The total number of new impersonated LDAP authentication
REQUESTS requests received.
ACTIVE REQUESTS The number of LDAP authentication requests active within the
Oracle BI Server.

Table 610 DBConnectionPool Category Parameters


Parameter Name Description
CAPACITY The maximum number of connections that the database
connection pool allows.
CONNECTION COUNT The current number of open connections in the thread pool.
BUSY CONNECTION The number of connections that have been assigned to process a
COUNT query, or that are currently processing a query, in the database
connection pool.
AVG REQUESTS PER SEC The average number of requests each second that have been
submitted to the database connection pool.
AVG OPEN REQUESTS The average number of connections that are opened each
PER SEC second. Connections might be opened for new connections,
because other connections timed out, or because of problems
with a connection.

Table 611 ThreadPool Category Parameters


Parameter Name Description
CAPACITY The maximum number of threads allowed by the thread pool.
THREAD COUNT The current number of threads in the thread pool.
BUSY THREAD COUNT The current number of threads that have been assigned work.
The thread might be blocked waiting for a resource or data, or it
could be actively running on a CPU.
ACCUMULATED The total number of requests that have been submitted to the
REQUESTS thread pool.
MAX STACK SIZE The maximum number of stack bytes consumed for all threads
in the thread pool.

Table 612 Cache Category Parameters


Parameter Name Description
CAPACITY The total capacity of the specified cache object.
TOTAL REQUESTS The total number of requests each second against the specified
cache object.
AVG REQUESTS The average number of requests each second against the
specified cache object.
AVG HITS The average number of hits each second for the specified cache
object.
AVG MISS The average number of misses each second for the specified
cache object.

6-28 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Troubleshooting System Startup

6.8 Troubleshooting System Startup


This section contains solutions that are related to system startup:
Section 6.8.1, "Administration Server Fails to Start When the Database Is Not
Running"
Section 6.8.2, "Managed Server Is Down"
Section 6.8.3, "Oracle BI Server Fails to Start"
Section 6.8.4, "Cannot Log In"

6.8.1 Administration Server Fails to Start When the Database Is Not Running
When you start the Administration Server, the repository database that was specified
during installation must be running, or else you see JDBC errors that prevent startup.
Problem: The Administration Server fails to start.
If the Administration Server fails to start, then:
View the Administration Server and Managed Server log files in the following
directory:
BI_DOMAIN/servers/AdminServer/logs
You can also check the Managed Server log files in the following directory:
BI_DOMAIN/servers/bi_server1/logs
Cause: Database Down: in AdminServer.log, "Caused By:
java.net.UnknownHostException: yourcomputername" deep in the trace from:
####<Jan 19, 2010 8:04:09 PM PST> <Info> <JDBC> <username> <AdminServer>
<[ACTIVE] ExecuteThread: '0' for queue: 'weblogic.kernel.Default (self-tuning)'>
<<anonymous>> <Stack trace associated with message 001129 follows:
java.sql.SQLException: The Network Adapter could not establish the connection.
Resolution: Start the database.

6.8.2 Managed Server Is Down


If the Managed Server is down, then use the command line to start it.
For information, see Section 2.3.2, "Starting Oracle Business Intelligence Component
Processes in a Domain."

6.8.3 Oracle BI Server Fails to Start


If the BI Server fails to start, then view the log files in the following directory:
BI_DOMAIN/servers/obis1/logs, or use the Log Viewer.

6.8.4 Cannot Log In


Problem: Cannot log in to Oracle WebLogic Server Administration Console.
Cause: The Administration Server is not running.
Resolution: Check to see if http://<host>:<port>/console starts. If not, start the BI
system. For information, see Section 2.3, "Using Commands to Stop, Start, and
View Status of Oracle Business Intelligence Processes."

Diagnosing and Resolving Issues in Oracle Business Intelligence 6-29


Troubleshooting System Startup

6-30 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
7
Managing Usage Tracking
7

This chapter describes how to manage usage tracking for Oracle Business Intelligence.
[8]

The Oracle BI Server supports the collection of usage tracking data. When usage
tracking is enabled, the Oracle BI Server collects usage tracking data for each query
and inserts it directly to a database table.

Note: The Oracle BI Summary Advisor feature works in conjunction


with the usage tracking feature. Summary Advisor only works with
direct insertion usage tracking.
Oracle BI Summary Advisor is only available when you are running
Oracle Business Intelligence on the Oracle Exalytics Machine. See
"Using Oracle BI Summary Advisor to Identify Query Candidates for
Aggregation" in Oracle Fusion Middleware Metadata Repository Builder's
Guide for Oracle Business Intelligence Enterprise Edition for more
information about the Summary Advisor feature.

This chapter includes the following sections:


About Usage Tracking
Setting Up Direct Insertion to Collect Information for Usage Tracking
Description of the Usage Tracking Data

7.1 About Usage Tracking


The Oracle BI Server supports the accumulation of usage tracking statistics that can be
used in a variety of ways such as database optimization, aggregation strategies, or
billing users or departments based on the resources that they consume. The BI Server
tracks usage at the detailed query level.
When you enable usage tracking, statistics for every query are inserted into a database
table or are written to a usage tracking log file. If you use direct insertion, then the BI
Server directly inserts the usage tracking data into a relational database table. It is
recommended that you use direct insertion to write statistics to a database table.
When the BI Server starts, it validates the column names in the metadata against the
list of valid columns in the usage tracking table. The following events occur:
Column names. If there is a mismatch between the columns in the database table
and the columns in the metadata, then it results in a database error on insert.

Managing Usage Tracking 7-1


Setting Up Direct Insertion to Collect Information for Usage Tracking

Varchar length. If the length in the metadata and the set length in the table do not
match, then an error is written to the nqserver.log file and usage tracking is
disabled.

Note: A sample usage tracking repository model is provided with


the Oracle Business Intelligence installation at:
ORACLE_HOME/bi/bifoundation/samples/usage_tracking.bar.
This path applies to 12c versions, but does not apply to earlier
versions.
To use the sample usage tracking repository, you modify the
connection pool to point to your database, then merge the usage
tracking repository with your existing repository.

7.2 Setting Up Direct Insertion to Collect Information for Usage Tracking


Direct insertion is the recommended method for setting up usage tracking. This
section describes how to set up direct insertion, and contains the following topics:
Section 7.2.1, "Setting Up the Usage Tracking Statistics Database"
Section 7.2.2, "Setting Direct Insertion Parameters"
Section 7.2.3, "Setting Optional Direct Insert Parameters"

7.2.1 Setting Up the Usage Tracking Statistics Database


Before you can use direct insertion usage tracking, you must set up a database to store
the usage tracking statistics. You must run the Repository Creation Utility (RCU) on
the target database to create the required statistics schemas.
Typically, you use the database you installed for use with Oracle Business Intelligence
as the statistics database because this database already has the RCU-created schemas.
The RCU-created table names for usage tracking are S_NQ_ACCT, S_NQ_DB_ACCT, and S_
NQ_INITBLOCK. See Section 7.3, "Description of the Usage Tracking Data" for more
information about these tables.
You also need to import the database into the Physical layer of the Oracle BI
repository.
To set up the usage tracking statistics database:
1. Run the Repository Creation Utility on an external database of your choice. You
can skip this step if you choose to use the database you installed for use with
Oracle Business Intelligence for usage tracking statistics, because this database has
the RCU-created tables already.
2. Open the Administration Tool and import the database into the Physical layer. See
Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business
Intelligence Enterprise Edition for more information.
3. Save and close the repository.

7.2.2 Setting Direct Insertion Parameters


To set up direct insertion for new (non-upgraded) installations, use a text editor.
To set up direct insertion usage tracking:

7-2 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Setting Up Direct Insertion to Collect Information for Usage Tracking

1. On the Oracle BI Server computer, open the NQSConfig.INI file in a text editor.
You can find this file at:
BI_DOMAIN/config/fmwconfig/biconfig/OBIS
Make a backup copy of the file before editing.
2. In the [USAGE_TRACKING] section, update the following parameters:
Set ENABLE to YES.
Set DIRECT_INSERT to YES.
Set PHYSICAL_TABLE_NAME to the name of the fully-qualified database table for
collecting query statistic information, as it appears in the Physical layer of the
Oracle BI repository. For example:
PHYSICAL_TABLE_NAME = "My_DB"."DEV_BIPLATFORM"."S_NQ_ACCT";

Set CONNECTION_POOL to the name of the fully-qualified connection pool for the
query statistics database, as it appears in the Physical layer of the Oracle BI
repository. For example:
CONNECTION_POOL = "My_DB"."Usage Connection Pool";

Set INIT_BLOCK_TABLE_NAME to the name of the fully-qualified database table


for inserting records that correspond to the initialization block statistics, as it
appears in the Physical layer of the Oracle BI repository. For example:
INIT_BLOCK_TABLE_NAME = "My_DB"."DEV.BIPLATFORM"."S_NQ_INITBLOCK;

Set INIT_BLOCK_CONNECTION_POOL to the name of the fully-qualified


connection pool for the table for inserting records that correspond to the
initialization block statistics, as it appears in the Physical layer of the Oracle BI
repository. For example:
INIT_BLOCK_CONNECTION_POOL = "My_DB"."Usage Connection Pool";

Note: For Usage Tracking insertions to succeed, the connection pool


must be configured with a user ID that has write access to the
back-end database. Also, it is recommended that the connectivity type
supports international data.

3. Save and close the file.


4. Restart the Oracle BI Server.

7.2.3 Setting Optional Direct Insert Parameters


In addition to the setup parameters described previously, you can also update the
following optional parameters in the Usage Tracking section of the NQSConfig.INI
file:
BUFFER_SIZE. This parameter indicates how much memory the BI Server
allocates for buffering the insert statements. Such a buffer lets the BI Server submit
multiple insert statements as part of a single transaction, improving Usage
Tracking insert throughput. It also means that ordinary analyses do not have to
wait on Usage Tracking insertions, which improves average query response time.
You might want to adjust this value based on available memory and memory
utilization on the server computer.

Managing Usage Tracking 7-3


Description of the Usage Tracking Data

BUFFER_TIME_LIMIT_SECONDS. This parameter indicates the maximum


amount of time that an insert statement remains in the buffer before the Usage
Tracking subsystem attempts to issue it. This time limit ensures that the BI Server
issues the insert statements quickly, even during periods of extended quiescence.
NUM_INSERT_THREADS. This parameter indicates the number of threads that
remove insert statements from the buffer and issue them to the Usage Tracking
database. Assuming separate connection pools for readers and inserters, the
number of insert threads typically equals the Maximum Connections setting in the
connection pool.
MAX_INSERTS_PER_TRANSACTION. This parameter indicates the maximum
number of insert statements that the Usage Tracking subsystem attempts to issue
as part of a single transaction. The larger this number, the greater potential
throughput for UsageMarathon Tracking inserts. However, a larger number also
increases the likelihood of transactions failing due to deadlocks. A small value for
BUFFER_TIME_LIMIT_SECONDS can limit the number of inserts per transaction.
See Appendix A.2, "NQSConfig.INI File Configuration Settings" for additional
information about the usage tracking configuration parameters.

7.3 Description of the Usage Tracking Data


Table 71 describes each column in the S_NQ_ACCT usage tracking table. Where
appropriate, the data type and length is also included.
As you review the descriptions in Table 71, you might assume that certain of the
time-related columns can be added or subtracted to equal exact values. For example,
you might assume that TOTAL_TIME_SEC is equal to END_TS minus START_TS. The
following list explains why the columns do not provide such exact values:
The various processes run in parallel and their speed depends on the load on the
BI Server and on database performance. The server-based operations might be
either light or intensive.
If all connections are full, then the query enters a queue and waits to be processed.
The timing depends on the load and configuration of the BI Server.

Table 71 Usage Tracking Data in S_NQ_ACCT


Column Description
CACHE_IND_FLG Default is N.
Y indicates a cache hit for the query; N indicates a cache miss.
COMPILE_TIME_SEC The time in seconds that is required to compile the query. The
number for COMPILE_TIME_SEC is included in TOTAL_TIME_
SEC, as described in this table.
CUM_DB_TIME_SEC The total amount of time in seconds that the BI Server waited for
back-end physical databases on behalf of a logical query.
CUM_NUM_DB_ROW The total number of rows that are returned by the back-end
databases.
END_DT The date the logical query was completed.
END_HOUR_MIN The hour and minute the logical query was completed.

7-4 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Description of the Usage Tracking Data

Table 71 (Cont.) Usage Tracking Data in S_NQ_ACCT


Column Description
END_TS The date and time that the logical query finished. The start and
end timestamps also reflect any time that the query spent waiting
for resources to become available.
Note: If the user submitting the query navigates away from the
page before the query finishes, then the final fetch never
happens, and a timeout value of 3600 is recorded. However, if the
user navigates back to the page before the timeout, then the fetch
completes at that time, and this is recorded as the end_ts time.
ERROR_TEXT Default is Null. Varchar(250)
Error message from the back-end database. This column is only
applicable if the SUCCESS_FLG (for more information, see entry
later in this table) is set to a value other than 0 (zero). Multiple
messages are concatenated and are not parsed by the BI Server.
ID The unique row ID.
NODE_ID Concatenates <hostname>:<instance_name>:<component_name>
where <instance_name>:<component_name> can be overridden by
the environment variables INSTANCE_NAME and
COMPONENT_NAME. For example,
examplehost:instance1:coreapplication_obis1.
Default value of INSTANCE_NAME is instance1, and default
value of COMPONENT_NAME is coreapplication_obis1.
NUM_CACHE_HITS Indicates the number of times that the cache result returned for
the query. NUM_CACHE_HITS is a 32-bit integer (or a 10-digit
integer).
Default is Null.
NUM_CACHE_ Indicates the number of times that the query generated a cache
INSERTED entry.
Default is Null. NUM_CACHE_INSERTED is a 32-bit integer (or
a 10-digit integer).
NUM_DB_QUERY The number of queries that were submitted to back-end
databases to satisfy the logical query request. For successful
queries (SuccessFlag = 0) this number is 1 or greater.
PRESENTATION_NAME Default is Null. Varchar(128)
The name of the Oracle BI Presentation Catalog.
QUERY_BLOB Contains the entire logical SQL statement without any truncation.
The QUERY_BLOB column is a long character string.
QUERY_KEY Default is Null. Varchar(128).
An MD5 hash key that is generated by Oracle Business
Intelligence from the logical SQL statement.
QUERY_SRC_CD The source of the request.
Values that can be inserted, for example:
An analysis, or any export operation inserts 'Report'.
Using the 'Value' drop down in a filter dialog, or using a
dashboard prompt inserts 'ValuePrompt'.
Agent to seed analytics server cache inserts 'Seed'.
Online Admin Tool physical table or column row count, or view
data inserts 'NULL'.

Managing Usage Tracking 7-5


Description of the Usage Tracking Data

Table 71 (Cont.) Usage Tracking Data in S_NQ_ACCT


Column Description
QUERY_TEXT Varchar(1024).
The SQL statement that was submitted for the query.
You can change the length of this column (using the ALTER
TABLE command), but note that the text that is written into this
column is always truncated to the size that is defined in the
physical layer. It is the responsibility of the repository
administrator not to set the length of this column to a value
greater than the maximum query length that is supported by the
back-end physical database.
For example, Oracle Databases enable a maximum Varchar of
4000, but Oracle Databases truncate to 4000 bytes, not 4000
characters. Hence, if you use a multibyte character set, the actual
maximum string size has a varying number of characters,
depending on the character set and characters used.
REPOSITORY_NAME The name of the repository that the query accesses.
ROW_COUNT The number of rows that are returned to the query client.
Note: When a large amount of data is returned from a query, this
column is not populated until the user displays all of the data.
IMPERSONATOR_USER_ Default is None. Varchar(128).
NAME
The user name of the impersonated user. If the request is not run
as an impersonated user, then the value is 'None'.
SAW_DASHBOARD The path name of the dashboard. If the query was not submitted
through a dashboard, then the value is NULL.
SAW_DASHBOARD_PG Default is Null. Varchar(150)
The page name in the dashboard. If the request is not a
dashboard request, then the value is NULL.
SAW_SRC_PATH The path name in the Oracle BI Presentation Catalog for the
analysis.
START_DT The date that the logical query was submitted.
START_HOUR_MIN The hour and minute that the logical query was submitted.
START_TS The date and time that the logical query was submitted.
SUBJECT_AREA_NAME The name of the business model that is being accessed.
SUCCESS_FLG The completion status of the query, as defined in the following
list:
0 - The query completed successfully with no errors.
1 - The query timed out.
2 = The query failed because row limits were exceeded.
3 = The query failed due to some other reason.
TOTAL_TIME_SEC The time in seconds that the BI Server spent working on the
query while the client waited for responses to its analyses.
TOTAL_TIME_SEC includes the time for COMPILE_TIME_SEC.
This setting is the same as the Response time in the nqquery.log
file, as described in Section 6.5.1.1, "Setting the Query Logging
Level."
USER_NAME The name of the user who submitted the query.

7-6 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Description of the Usage Tracking Data

Table 72 describes the S_NQ_DB_ACCT table, which supplements the usage tracking
table by providing the physical SQL information for the logical queries stored in S_NQ_
ACCT. S_NQ_DB_ACCT has a foreign key relationship back to S_NQ_ACCT.

Table 72 Usage Tracking Data in S_NQ_DB_ACCT


Column Description
END_DT The date the physical query was completed.
END_HOUR_MIN The hour and minute the physical query was completed.
END_TS The date and time the physical query finished. The start and
end timestamps also reflect any time that the query spent
waiting for resources to become available.
ID The unique row ID.
LOGICAL_QUERY_ID Varchar2(50).
Refers to the logical query in the S_NQ_ACCT table.
QUERY_BLOB Contains the entire physical SQL statement without any
truncation.
The QUERY_BLOB column is a long character string.
QUERY_TEXT Varchar(1024).
The SQL statement that was submitted for the query.
ROW_COUNT The number of rows that are returned to the query client.
TIME_SEC The physical query execution time.
START_DT The date that the physical query was submitted.
START_HOUR_MIN The hour and minute that the physical query was submitted.
START_TS The date and time that the physical query was submitted.

Table 73 describes each column in the S_NQ_INITBLOCK usage tracking table, which
tracks information about initialization blocks.

Table 73 Usage Tracking Data in S_NQ_INITBLOCK


Column Description
USER_NAME Varchar2(128).
The name of the user who ran the initialization block.
REPOSITORY_NAME Varchar2(128).
The name of the repository that the query accesses.
TENANT_ID Varchar2(128).
The name of the tenant of the user who ran the initialization
block.
SERVICE_NAME Varchar2(128).
The name of the service.
ECID Varchar2(1024).
The system-generated execution context ID.
SESSION_ID Number(10).
The ID of the session.

Managing Usage Tracking 7-7


Description of the Usage Tracking Data

Table 73 (Cont.) Usage Tracking Data in S_NQ_INITBLOCK


Column Description
BLOCK_NAME Varchar2(128).
The name of the initialization block that was executed.
START_TS The date and time that the initialization block started.
END_TS The date and time that the initialization block finished. The start
and end timestamps also reflect any time that the query spent
waiting for resources to become available.
DURATION Number(13,3).
The length of time it took to execute the initialization block.
NOTES Varchar2(1024).
Notes about the initialization block and its execution.

7-8 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Part V
Part V Configuring Oracle Business Intelligence

Although the installer installs Oracle Business Intelligence and the configuration
assistant provides a functional sample application, some functionality requires
additional configuration changes (for example, the specification of connection details
to external systems and email systems). You can also modify default configuration
settings to adapt Oracle Business Intelligence to your environment and user needs.
This part includes the following chapters:
Chapter 8, "Using Tools for Managing and Configuring Oracle Business
Intelligence"
Chapter 9, "Managing Metadata and Working with Service Instances"
Chapter 10, "Configuring Connections to External Systems"
Chapter 11, "Configuring Presentation Setting Defaults"
Chapter 12, "Configuring Mapping and Spatial Information"
Chapter 13, "Configuring Time Zones"
Chapter 14, "Localizing Oracle Business Intelligence"
Chapter 15, "Configuring Currency Options"
Chapter 16, "Configuring and Managing the Oracle BI Presentation Catalog"
8
Using Tools for Managing and Configuring
8

Oracle Business Intelligence

This chapter introduces the tools to manage and configure Oracle Business Intelligence
[9]

including Fusion Middleware Control, WebLogic Server Administration Console, a


text editor, and the WebLogic Scripting Tool.
This chapter includes the following sections:
Why Use Fusion Middleware Control and WebLogic Server Administration
Console?
Managing Oracle Business Intelligence System Components Using Fusion
Middleware Control
Configuring Oracle Business Intelligence System Settings
Managing Oracle Business Intelligence Java Components Using the Oracle
WebLogic Server Administration Console

8.1 Why Use Fusion Middleware Control and WebLogic Server


Administration Console?
You can use Fusion Middleware Control and WebLogic Server Administration Console
to manage the Oracle Business Intelligence system. These Web-based tools support the
most common system administration tasks for Oracle Business Intelligence. For more
information, see Section 1.2, "Getting Started with Managing Oracle Business
Intelligence."
Fusion Middleware Control enables you to manage system components by performing
tasks such as monitoring status, starting and stopping processes, resolving issues, and
configuring components. You can also manage some aspects of Java components. For
example, you can monitor their status and start and stop them.
WebLogic Server Administration Console enables you to monitor status and configure
security for Java components. For information, see Chapter 1, "Introduction to Oracle
Business Intelligence System Administration."

Locking Mechanism Enables Multiple Concurrent Administrators


With large deployments, you might have multiple administrators accessing the system
concurrently to view the state of the system while other administrators might want to
make configuration changes. Fusion Middleware Control and Oracle WebLogic Server
prevent concurrent updates of the same configuration settings by multiple
administrators by using a locking mechanism that enables only one administrator to
make changes at any one time.

Using Tools for Managing and Configuring Oracle Business Intelligence 8-1
Managing Oracle Business Intelligence System Components Using Fusion Middleware Control

Note: Multiple administrators using the same administrator account


could unknowingly make concurrent updates of the same
configuration settings. It is therefore recommended that multiple
administrator users do not share the same administrator account.

8.2 Managing Oracle Business Intelligence System Components Using


Fusion Middleware Control
You can use Fusion Middleware Control to manage, monitor, and configure Oracle
Business Intelligence system components (for example, the Oracle BI Server, Oracle BI
Presentation Services, and Oracle BI Scheduler). You can also use Fusion Middleware
Control to manage the Administration Server and Managed Servers.
This section contains the following topics:
Section 8.2.1, "Logging into Fusion Middleware Control"
Section 8.2.2, "Displaying Oracle Business Intelligence Pages in Fusion
Middleware Control"
Section 8.2.3, "Using the Navigation Tree in Fusion Middleware Control"
Section 8.2.4, "Tips for Using Fusion Middleware Control with Oracle Business
Intelligence"

8.2.1 Logging into Fusion Middleware Control


To log in to Fusion Middleware Control, open a web browser and enter the Fusion
Middleware Control URL, in the following format:
http://hostname.domain:port/em

The port number is the number of the Administration Server, and the default port
number is 9500.
Fusion Middleware Control is available only if the Administration Server is running,
as described in Section 2.2, "Conditions for Starting the Oracle Business Intelligence
System."
To log in to Fusion Middleware Control:
1. Enter the URL in a web browser. For example:
http://host1.example.com:9500/em

2. Enter the system administrator user name and password and click Login.
This systemwide administration user name and password was specified during
the installation process, and you can use it to log in to WebLogic Server
Administration Console, Fusion Middleware Control, and Oracle Business
Intelligence.
Alternatively, enter any other user name and password that has been granted the
Oracle BI Administrator application role. Fusion Middleware Control is displayed.

8-2 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Managing Oracle Business Intelligence System Components Using Fusion Middleware Control

Note: If you have the browser configured to send HTTP requests to a


proxy server, then you might have to configure the browser to not
send Administration Server HTTP requests to the proxy server. If the
Administration Server is on the same computer as the browser, then
ensure that requests that are sent to localhost or 127.0.0.1 are not sent
to the proxy server.

8.2.2 Displaying Oracle Business Intelligence Pages in Fusion Middleware Control


Use this topic to display Oracle Business Intelligence pages that enable you to manage
Oracle Business Intelligence system components:
To display Oracle Business Intelligence pages in Fusion Middleware Control:
1. Log in to Fusion Middleware Control.
For more information, see Section 8.2.1, "Logging into Fusion Middleware
Control."
2. Expand the Business Intelligence folder and select the biinstance node.
Fusion Middleware Control displays the Overview page, as shown in Figure 81.

Figure 81 Overview Page in Fusion Middleware Control

Note: If the Business Intelligence folder is not visible or there is no


biinstance node under it, then Oracle Business Intelligence system
components have not been installed. For information, see Oracle
Fusion Middleware Installation Guide for Oracle Business Intelligence.

The Overview page displays the current system status, by providing information
about availability, and issues identified within the BI domain (for more
information, see Section 1.3, "What Is the Oracle Business Intelligence System
Logical Architecture?"). The Overview page also enables you to start and stop
Oracle Business Intelligence.

Using Tools for Managing and Configuring Oracle Business Intelligence 8-3
Managing Oracle Business Intelligence System Components Using Fusion Middleware Control

3. From the Overview page, select an appropriate tab to perform Oracle Business
Intelligence management tasks.

8.2.3 Using the Navigation Tree in Fusion Middleware Control


The navigation tree enables you to navigate and select nodes within the BI domain
that can be managed by Fusion Middleware Control.
Depending on the choices made during installation, the following domain components
can be displayed as nodes in the navigation tree:
Application Deployments
The Application Deployments node shows all the applications that are deployed
into the BI domain (for example, analytics, Oracle Business Intelligence for
Microsoft Office, Oracle BI Publisher).
WebLogic Domain
These nodes display summary information for the WebLogic server. Select a node
and click the Oracle WebLogic Server Administration Console menu option to
display the WebLogic Server Administration Console, where you can administer
Oracle WebLogic Server.
bi
This node represents the WebLogic server domain for Oracle Business
Intelligence with an AdminServer node that contains the Administration
Server and a bi_cluster node that contains Managed Servers (a single node
cluster by default, for example, bi_server1). For information, see Section 1.3.3,
"About the Administration Server, Managed Servers, and System
Components"
* AdminServer
* bi_cluster
Business Intelligence
biinstance
This node represents the Oracle Business Intelligence system components that
can be managed using Fusion Middleware Control.
Select this node to display the Overview page and manage the system
components.
Metadata Repositories
This node represents the Metadata Services (MDS) schema repositories that can be
managed using Fusion Middleware Control.

8.2.4 Tips for Using Fusion Middleware Control with Oracle Business Intelligence
Keep the following tips in mind as you use Fusion Middleware Control to manage
Oracle Business Intelligence:
For complete information about Fusion Middleware Control and how to use it, see
Oracle Fusion Middleware Administrator's Guide.
You might want to have a user who can view information about Oracle Business
Intelligence within Fusion Middleware Control but not make any changes. You
can configure such a user by making him a member of the Monitors group. See

8-4 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Configuring Oracle Business Intelligence System Settings

Oracle Fusion Middleware Securing Resources Using Roles and Policies for Oracle
WebLogic Server for information on the Monitors group.
You might encounter display problems when using Internet Explorer 8 with
Fusion Middleware Control. For example, scroll bars might be missing on the Log
Messages tab of the Diagnostics page, even when the bars are required to see all
the text.
To work around this issue, ensure that Compatibility View mode is turned off for
the browser.
To turn off compatibility view mode in Internet Explorer 8:
1. From the Tools menu, select Internet Options. On the Advanced tab in the
Browsing section, ensure that Automatically recover from page layout errors
with Compatibility View is not checked.
2. From the Tools menu, select Compatibility View Settings. Ensure that
Display intranet sites in Compatibility View and Display all websites in
Compatibility View are not checked.

8.3 Configuring Oracle Business Intelligence System Settings


You configure the Oracle Business Intelligence system settings by changing values
stored in domain-specific locations related to either functional behavior (for example,
cache, thresholds), or environmental settings (for example, host names, ports, files or
metadata locations).
You can use the following methods:
Using Fusion Middleware Control
Using a Text Editor
Using the WebLogic Scripting Tool (WLST)
Table 81 shows which method to use when configuring Oracle Business Intelligence
system settings. Each method updates settings in specific configuration files.

Using Tools for Managing and Configuring Oracle Business Intelligence 8-5
Configuring Oracle Business Intelligence System Settings

Table 81 Methods for Configuring Oracle Business Intelligence System Settings


What to you want to do? What methods can you use? How are updates made?
Change common Fusion Middleware Control Change values in specific
configuration settings in an Oracle Business Intelligence
For information, see Section 8.3.1, "Using
easy to use user interface. configuration pages in
Fusion Middleware Control."
Fusion Middleware Control.
Note: Oracle recommends that you use this
For example, to enable the
method. However, if a setting is not available,
BI Server cache, you click
you can use a text editor.
the Cache Enabled check
box (select/clear) in the
Performance tab of the
Configuration page.
Change configuration Text editor Change values in a
settings by manually editing configuration text file using
For information, see Section 8.3.2, "Using a Text
a file. a text editor.
Editor".
Note: Oracle recommends that you use this
method when a setting is not available in
Fusion Middleware Control Oracle Business
Intelligence pages.
Make more complex WebLogic Scripting Tool (WLST) Make configuration changes
configuration changes using by running commands
For information, see Section 8.3.3, "Using the
a scripting tool. using the WLST scripting
WebLogic Scripting Tool (WLST)".
tool.
Note: Oracle recommends that you use this
method when instructed by the documentation.

8.3.1 Using Fusion Middleware Control


You can use Fusion Middleware Control to update specific Oracle Business
Intelligence configuration settings. For example, performance settings, dashboard and
analysis default presentation settings, and mail server settings used by agents. For
more information see the help.
If an Oracle Business Intelligence configuration setting is not available in Fusion
Middleware Control, you can use a text editor to update the setting in a configuration
file. For information, see Configuring Oracle Business Intelligence System Settings.
To update Oracle Business Intelligence configuration settings using Fusion
Middleware Control:
1. Go to the Business Intelligence Overview page, as described in Section 8.2.2,
"Displaying Oracle Business Intelligence Pages in Fusion Middleware Control."
2. Select the appropriate page and tabs to display the settings to change.
3. Click Lock and Edit to enable changes to be made.

Note: Oracle recommends that multiple administrators do not share


the same administrator account. They can unknowingly make
concurrent updates to the same configuration settings.

4. Make the appropriate changes on each page.


5. Click Apply on each page after you have made your changes.
6. When you have finished making your changes, do one of the following:

8-6 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Configuring Oracle Business Intelligence System Settings

Click Activate Changes to execute your changes and release the lock to enable
another system administrator to make changes.
Click Release Configuration to undo all changes you made since clicking
Lock and Edit and release the lock to enable another system administrator to
make changes.
7. After you have activated your changes, go to the Overview page and click Restart.

8.3.2 Using a Text Editor


You can use a text editor to add or change a setting in a configuration file. You would
use text editor for the system configuration settings that are not available in Fusion
Middleware Control.
Use the following procedure to update configuration files using a text editor.
To update a configuration settings using a text editor:
1. Make a backup copy of the files that you plan to edit.
2. Open the appropriate configuration file in a text editor.
For information, see Appendix A.1, "Configuration Files"
3. In the configuration file, locate the element or create a new element if you must
add a setting to the file.
4. Enter the appropriate changes.
5. Save your changes and close the configuration file.
6. Restart Oracle Business Intelligence.
For information, see Section 2.1, "About Managing Oracle Business Intelligence
Processes."

8.3.3 Using the WebLogic Scripting Tool (WLST)


Oracle provides WebLogic Scripting Tool (WLST) scripts to perform Oracle Business
Intelligence WebLogic configuration tasks. For example, to create a domain during
installation, or to add a machine for high availability.
You run WLST scripts commands from the following location:
ORACLE_HOME/oracle_common/common/bin/wlst.sh
For information, see Section 8.3.3, "Using the WebLogic Scripting Tool (WLST)".
You can configure Oracle Business Intelligence system settings in online (system
processes running) or offline (system processes stopped) mode. The following sections
describe the different conditions that apply when making online and offline
configuration changes.
Making Offline Configuration Changes
Making Online Configuration Changes

8.3.3.1 Making Offline Configuration Changes


All offline configuration changes must be made on the master host, except those
relating to node managers, and all Oracle BI EE processes must be stopped first. To
consume offline changes you must start the Administration server, Managed servers,
and then system components (in that order). This is the general requirement for any

Using Tools for Managing and Configuring Oracle Business Intelligence 8-7
Configuring Oracle Business Intelligence System Settings

configuration change as the command to start the managed server is the only process
that replicates the configuration, from a running Administration Server.

Assumptions and pre-requisites:


You must have file system (offline) or Weblogic Administrator (online)
permissions
When you start component(s) offline, the Administration server and node
managers must be started first, see Section 2.3.2, "Starting Oracle Business
Intelligence Component Processes in a Domain"

Running WLST Offline


You run WLST scripts commands from the following location:
ORACLE_HOME/oracle_common/common/bin/wlst.sh
Before issuing offline commands you must select a domain using the
readDomain(DOMAIN_HOME) command.
For example:
readDomain('/u01/bi')

After you have issued your offline commands you must commit the changes using
the updateDomain() command.
For example:
updateDomain('/u01/bi')

De-select the domain using the closeDomain() command.


For example:
closeDomain('/u01/bi')

If you make a mistake or decide to abandon changes, you should use the
closeDomain() command without using the updateDomain() command.

8.3.3.2 Making Online Configuration Changes


You can make online configuration changes from any computer where you have access
to the Administration Server domain mbeans.

Assumptions and pre-requisites:


You must have Weblogic Administrator permissions.
The Administration Server must be running.
After making changes, you must restart the affected BI component(s), see
Section 2.3.2, "Starting Oracle Business Intelligence Component Processes in a
Domain".

Running WLST Online


You run WLST script commands from the following location:
ORACLE_HOME/oracle_common/common/bin/wlst.sh
Connect to Administration Server by issuing the following command:
./wlst.sh connect(<username>, <password>, <connect string>)

8-8 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Managing Oracle Business Intelligence Java Components Using the Oracle WebLogic Server Administration Console

For example,
./wlst.sh connect('weblogic', 'mypassword', 't3://localhost:9500')

You must enter edit tree and start an edit session by issuing edit() and startEdit()
commands before issuing commands.
Use the save() command to save all changes made during the edit session.
Use the activate() command to commit your changes.
If you attempt to issue a command outside an edit session, the command will fail and
display a help message.
If you make a mistake or decide to abandon changes then you must use the undo() or
cancelEdit() command.

8.3.4 Updating the Java Development Kit (JDK)


After you install and configure Oracle Business Intelligence, you might need to update
the JDK for the instance; for example, if an update is required per the policy of your
organization. Before deciding to update the JDK, ensure that you consider an
appropriate version, as described in the system requirements and certification
documentation. For information, see Section 1.9, "System Requirements and
Certification."
To update the JDK for the instance of Oracle Business Intelligence:
1. Stop all services for Oracle Business Intelligence.
2. Download the appropriate JDK version from the Oracle Java web site and copy it
to the ORACLE_HOME directory.
3. Rename the existing jdk directory to jdk.OLD.
4. Run the JDK Installer, which unzips the distribution into the jdkversion-num
directory.
5. Rename the directory from jdkversion-num to jdk, to ensure that all existing
configuration references remain valid.
6. Restart the services for Oracle Business Intelligence.
For information on installing with a specific JDK, see Oracle Fusion Middleware
Installation Guide for Oracle Business Intelligence.

8.4 Managing Oracle Business Intelligence Java Components Using the


Oracle WebLogic Server Administration Console
You use the Oracle WebLogic Server Administration Console to manage Oracle
Business Intelligence Java components.
You display Oracle WebLogic Server Administration Console, using the following
methods:
Clicking a link on the WebLogic Domain menu in Fusion Middleware Control
Entering a URL into a web browser window
The Oracle WebLogic Server Administration Console is available only if the
Administration Server for WebLogic Server is running. For information, see
Section 2.1, "About Managing Oracle Business Intelligence Processes."
To display Oracle WebLogic Server Administration Console:

Using Tools for Managing and Configuring Oracle Business Intelligence 8-9
Managing Oracle Business Intelligence Java Components Using the Oracle WebLogic Server Administration Console

1. If the Administration Server for WebLogic Server is not running, start it.
For information, see Section 2.3, "Using Commands to Stop, Start, and View Status
of Oracle Business Intelligence Processes."
2. Display the Oracle WebLogic Server Administration Console using the following
methods:
Clicking a link on the Overview page in Fusion Middleware Control:
a. Display Fusion Middleware Control. For information, see Section 8.2.2,
"Displaying Oracle Business Intelligence Pages in Fusion Middleware
Control."
b. Click the Oracle WebLogic Server Administration Console link in the
WebLogic Domain menu.
The Oracle WebLogic Server Administration Console login page is displayed.
Using a URL in a web browser window:
a. Start a web browser.
b. Enter the following URL into the browser:
http://<hostname>:<port>/console/
For example, http://example.com:9500/console/
where hostname is the DNS name or IP address of the Administration Server
and port is the listen port on which the Administration Server is listening for
requests (port 9500 by default). If you have configured a domain-wide
Administration port, then use that port number. If you configured the
Administration Server to use Secure Sockets Layer (SSL), then you must add
the letter 's' after http as follows:
https://<hostname>:9500/console/
The preceding URL example uses SSL.
The Oracle WebLogic Server Administration Console login page is displayed.
3. Enter the system administrator user name and password and click Login.
This systemwide administration user name and password was specified during
the installation process, and you can use it to log in to WebLogic Server
Administration Console, Fusion Middleware Control, and Oracle Business
Intelligence. Alternatively, enter a user name that belongs to one of the following
security groups:
Administrators
Operators
Deployers
Monitors
These groups provide various levels of access to system administration functions
in the Oracle WebLogic Server Administration Console.
Using the security system, you can add to or delete users from one of these groups
to provide controlled access to the Console.
If you have the browser configured to send HTTP requests to a proxy server, then
you might have to configure the browser to not send Administration Server HTTP
requests to the proxy. If the Administration Server is on the same computer as the

8-10 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Managing Oracle Business Intelligence Java Components Using the Oracle WebLogic Server Administration Console

browser, then ensure that requests sent to localhost or 127.0.0.1 are not sent to the
proxy.
In Oracle WebLogic Server Administration Console you select the bi domain, as
shown in Figure 82.

Figure 82 Settings for bi Page in WebLogic Server Administration Console

You can monitor and manage Oracle Business Intelligence Java components from
this page.

Note: For more information on using the Oracle WebLogic Server


Administration Console, see the Oracle WebLogic Server Administration
Console Help system. That Help system describes how to use the
console to override the context root for a deployed web application.
Changing any context root for Oracle Business Intelligence is not
supported, because many context roots are used for internal links and
end-user end points.

Using Tools for Managing and Configuring Oracle Business Intelligence 8-11
Managing Oracle Business Intelligence Java Components Using the Oracle WebLogic Server Administration Console

8-12 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
9
Managing Metadata and Working with Service
9

Instances

[10T
] his chapter describes how to manage Oracle Business Intelligence metadata in BI

Application Archive (BAR) files, and how to work with Service Instances.
This chapter includes the following sections:
About Oracle Business Intelligence Application Archive (BAR) Files
Managing Service Instances

9.1 About Oracle Business Intelligence Application Archive (BAR) Files


This topic contains the following sections:
What Are Oracle Business Intelligence Application Archive (BAR) Files?
What Predefined BAR Files are Available?
About Importing BAR Files

9.1.1 What Are Oracle Business Intelligence Application Archive (BAR) Files?
An Oracle Business Intelligence application archive (BAR) file is a compressed archive
file that contains a cohesive set of BI metadata artifacts (data model, content model,
and authorization model). A BAR file can be imported into a BI Service Instance. You
can backup a BI Service Instance into a BAR file, and subsequently restore it either to
the existing service instance running in the BI domain, or into a different service
instance running on a different BI installation.
A BAR file contains the following BI application module artifacts:
Data model metadata for the Oracle BI Server. This metadata is xml-based but
functionally equivalent to a .RPD file.
Presentation Services catalog metadata for a service instance.
Security policy metadata containing application role and application role
memberships plus permission and permission set grants for a service instance.
A manifest file declaring the dependencies for the BAR file.

9.1.2 What Predefined BAR Files are Available?


Oracle provides a number of predefined BAR files, containing BI metadata to use with
a service instance.
You can choose one of the following BAR files during installation:

Managing Metadata and Working with Service Instances 9-1


About Oracle Business Intelligence Application Archive (BAR) Files

Empty BAR - oracle.bi.application.empty.bar


The empty BAR file enables you to have complete control over metadata and
security policy, or you may simply have an existing BAR from another system that
you might want to import.
ORACLE_
HOME/bi/bifoundation/admin/provisioning/oracle.bi.application.empty.bar
The Empty BAR file contains only enough permissions for the administrator user
to login and administer the system.
Table 91 shows the application role and corresponding permission sets that come
with the Empty BAR file.

Table 91 Application Role And Permission Sets in Empty BAR


Application Role Permission Set
BIServiceAdministrator obisch.administrator
essbase.administrator
obips.administrator
cds.administrator
bip.administrator
obis.administrator

SampleAppLite BAR - SampleAppLite.bar


You can select SampleAppLite at install time (see Oracle Fusion Middleware
Installation Guide for Oracle Business Intelligence).
The SampleAppLite BAR enables you to start using BI Analytics straight away,
enabling you to demonstrate the functionality of the product.
The SampleAppLite BAR file contains a file based data source with 2 subject areas,
a collection of reports, and application roles for read, write, and administration
tasks.
ORACLE_HOME/bi/bifoundation/samples/sampleapplite/SampleAppLite.bar
Table 92 shows the application roles and corresponding permission sets that
come with the SampleAppLite BAR file.

Table 92 Application Roles And Permission Sets in SampleAppLite BAR


Application Role Permission Set
BIServiceAdministrator obisch.administrator
essbase.administrator
obips.administrator
cds.administrator
bip.administrator
obis.administrator
BIConsumer bip.consumer
BIContentAuthor va.author
obisch.author
bip.author

9-2 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Managing Service Instances

For more information, see Section 1.6, "Working with the Sample Application".
Starter BAR
You use the starter BAR when you want to build metadata from the beginning, but
need a typical security policy to be in place.
The starter BAR is essentially empty except for containing the same security policy
as the Sample application BAR.
For example, if you want to create a service instance for Visual Analyzer where
users will import their own data from scratch, by importing the starter BAR into
your service instance it means that you only have to provision users with the
starter application roles and they can immediately login and start using the
product.

9.1.3 About Importing BAR Files


When you import a BAR file into a service instance, the service instance will use the
data model, content and security policy imported from the BAR file.
The import process does the following:
Takes the content, model and security policy defined by the BAR, and deploys it to
a Service Instance.
Overwrites any existing content, model, security policy already established in the
Service Instance.

9.2 Managing Service Instances


A service instance contains all of the Oracle Business Intelligence metadata (that is,
repository data, presentation catalog, security policy), and includes the customizations
that you make to the metadata. You manage a service instance in an BI domain using
WebLogic Scripting Tool (WLST) commands described in Table 93.
For information about using WLST, see Section 8.3.3, "Using the WebLogic Scripting
Tool (WLST)").

Table 93 Oracle Business Intelligence Service Instance Commands


Command Description
"listBIServiceInstances" This command lists all Service Instance keys in the BI domain.
"getBIServiceInstance" This command gets service instance details for a given service instance key.
"scaleOutBIServiceInstance" This command scales-out the Service Instance(s) onto the new computer, ensuring
that the service instance is available on the specified computer within the BI domain.
This command is only used in advanced cases.
"exportServiceInstance" This command exports a service instance to a given export directory in the form of
BAR file.
"importServiceInstance" This command imports an already exported bar (service instance) as a customization
to a given environment.

Managing Metadata and Working with Service Instances 9-3


Managing Service Instances

Table 93 (Cont.) Oracle Business Intelligence Service Instance Commands


Command Description
"refreshServiceInstance" This command refreshes certain aspects of a service instance serviceKeythat are
inherited from the BI domain. For example, if a new module or product is added to
the BI domain, the permission sets for that module or product will only be made
available to the service instance when the service instance is refreshed.
"refreshDomainServiceInstances" This command refreshes all the service instances of the domain.
"resetServiceInstance" This command resets the given service instance to empty state equivalent to
importing the empty BAR file.

Table 94 Parameters Used With 'Managing Domain Service Instances' Commands


Parameters Description
domainHome Path to BI domain home.
/oraclehome/user_projects/domains/bi
serviceInstanceKey Key for the service instance to be associated with, or scaled out
to.
For example:
mycompany.facility
machine Name of the computer to which you are scaling out.
For example:
machine=mycompany.example.com
port The port number to use on the scaled out computer.
For example:
port=9768
monitorPort Name of the monitor port to use on the scaled out computer.
For example:
portMonitor=9502

Assumptions for all WLST commands against BI Service Instances and BAR files:
You must have file system (offline) permissions.
You run the WLST commands offline.
You must start your system after making changes to service instances through
WLST.

9.2.1 listBIServiceInstances
This task enables you to list all Service Instances.
To list all service instances:
1. Start the WLST command line scripting tool.
For information, see Section 8.3.3, "Using the WebLogic Scripting Tool (WLST)".
2. Enter command, for example:
listBIServiceInstances(domainHome)
Where domainHome is the path to BI domain home.

9-4 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Managing Service Instances

For example:
listBIServiceInstances('/oraclehome/user_projects/domains/bi')

3. The command returns a list of Service Instance Keys


For more information, see Section 9.2.2, "getBIServiceInstance"

9.2.2 getBIServiceInstance
This command displays service instance details. Information includes but is not
limited to:
Metadata configuration: application association and customizations.
Component details.
Description.
To display service instance details:
1. Enter the following command to fetch the specified Service Instance details:
getBIServiceInstance(domainHome, serviceInstanceKey)
For example:.
getBIServiceInstance('/oraclehome/user_projects/domains/bi',
'mycompany.facility')

2. The command returns a service instance object containing details including, but
not limited to:
Service instance key.
Description.
List of components.
List of application modules.

9.2.3 scaleOutBIServiceInstance
This command scales-out the service instance(s) onto a new computer to make the
service instance available in the domain. Use this command if a service instance is
created after availability is increased. For more information, see "Managing
Availability in Oracle Business Intelligence (Horizontally Scaling)".
scaleOutBIServiceInstance(domainHome, serviceInstanceKey, machine, port=None,
portMonitor=None)
This command returns a Service Instance object containing details.
Assumptions:
All ports will be allocated from the default BI port range, unless you provide
them.
Cluster Controller, Scheduler and BI Server mastership is unchanged.
You must start new component(s), noting that Administration Server and Node
Managers must be started first if offline, see Section 2.3.2, "Starting Oracle
Business Intelligence Component Processes in a Domain".
Table 95 lists the parameters for this command.

Managing Metadata and Working with Service Instances 9-5


Managing Service Instances

Table 95 Parameters For Scaling Out a Service Instance For High Availability
Parameters Description
domainHome Path to BI domain home.
serviceInstanceKey Key for the service instance to be scaled out.
machine Name of the computer to which you are scaling out the service
instance.

For example,
scaleOutBIServiceInstance('/oraclehome/user_
projects/domains/bi','mycompany.facility', 'example.com')

Post Conditions:
New component(s) are created.
New ports(s) are allocated.
New Service Instance is registered.

9.2.4 exportServiceInstance
This command exports a service instance to a specified export directory as a BAR file.
You can then import the BAR file into another environment or within the same
environment. Details of these optional parameters are given in Table 96.
exportServiceInstance(domainHome serviceInstanceKey workDir, exportDir,
applicationModuleName, applicationModuleDesc, applicationModuleVersion,
includeCatalogRuntimeInfo, includeCredentials)
Table 96 lists the parameters for this command.

Table 96 Parameters For Exporting A Service Instance


Parameters Description
domainHome Path to BI domain home.
serviceInstanceKey Key for the service instance.
workDir Work directory for the run.
exportDir Directory where BAR file is to be exported
applicationModuleName Reserved for future use.
applicationModuleDesc Reserved for future use.
applicationModuleVersion Reserved for future use.
includeCatalogRuntimeInfo Optional - If this flag is true, catalog runtime info (for example,
user folder) is included in export. Otherwise catalog runtime
info is skipped. The default value of this flag is false.
includeCredentials Optional - This is the password to encrypt the exported
metadata repository content. The default value for this field is
None. If you do not specify this value, connection credentials are
not exported, otherwise, connection credentials are exported.

For example,
exportServiceInstance( '/oraclehome/user_
projects/domains/bi','mycompany.facility', '/workDir', '/scratch/exportDir')

9-6 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Managing Service Instances

exportServiceInstance('/oraclehome/user_projects/domains/bi/','mycompany.dev',
'/scratch/workDir', '/scratch/exportDir', 'mycompany.dev.test' , 'mycompany dev
test', '11.1.1.0')

exportServiceInstance('/oraclehome/user_projects/domains/bi/','mycompany.dev',
'/scratch/workDir', '/scratch/exportDir', 'mycompany.dev.test' , 'mycompany dev
test', '11.1.1.0', true, 'Test123')

exportServiceInstance('oraclehome/user_projects/domains/bi/','mycompany.dev',
'/scratch/workDir', '/scratch/exportDir', 'mycompany.dev.test' , 'mycompany dev
test')

exportServiceInstance('/oraclehome/user_
projects/domains/bi/','mycompanyexample.dev', '/scratch/workDir',
'/scratch/exportDir', None , 'mycompany dev test')

9.2.5 importServiceInstance
This command imports the BI metadata from a specified BAR file into a target service
instance.
importServiceInstance(domainHome, serviceInstanceKey, barLocation, importRpd,
importWebcat, importJazn, includeCredentials, includeCatalogRuntimeInfo,
includeCredentials)
Table 97 lists the parameters for this command.

Table 97 Parameters For Importing A Service Instance


Parameters Description
domainHome Path to BI domain home.
serviceInstanceKey Key for the service instance.
barLocation Exported service instance bar absolute path.
importRpd Optional - The value of this parameter can be true or false. The
default value is 'true'. This parameter support selective import
of metadata. If this flag is set to be 'false', the command run does
not import the repository metadata.
importWebcat Optional - The value of this parameter can be true or false. The
default value is 'true'. This parameter supports selective import
of the catalog. If this flag is false, the command does not import
the catalog.
importJazn Optional - The value of this parameter can be true or false. The
default value is 'true'. This parameter supports selective import
of the Jazn. If this flag is false, the command does not import the
Jazn.
includeCredentials Optional - This password is used to decrypt the imported rpd
content. Default value for this field is "Admin123".
includeCatalogRuntimeInfo Optional - If this flag is true the catalog runtime info (user folder
etc.) is included in export. Otherwise catalog runtime info is
skipped. The default value of this flag is false.
includeCredentials Optional - This password encrypts the exported metadata
repository content. The default value is None. If this parameter
is not specified connection credentials are not exported.
Otherwise, connection credentials are exported.

Managing Metadata and Working with Service Instances 9-7


Managing Service Instances

For example,
importServiceInstance( '/scratch/mydir/oraclehome/user_
projects/domains/bi','mycompany.facility',
'/scratch/exportDir/mycompany.finance.bar')

importServiceInstance('/scratch/mydir/oraclehome/user_projects/domains/bi',
'demosvc1',
'/scratch/mydir/oraclehome/bi/bifoundation/samples/sampleapplite/test/SampleAppLit
e1.bar', true, false, false, 'Test123')

importServiceInstance('/scratch/mydir/oraclehome/user_projects/domains/bi',
'demosvc1',
'/scratch/mydir/orahome/bi/bifoundation/samples/sampleapplite/test/SampleAppLite1.
bar', importRPD=true,includeCredentials='Test123')

9.2.6 refreshServiceInstance
This command refreshes certain aspects of a service instance that are inherited from
the BI domain. For example, if a new module or product is added to the BI domain,
the permission sets for that module or product will only be made available to the
service instance when the service instance is refreshed.
refreshServiceInstance(domainHome, serviceKey)
Table 98 lists the parameters for this command.

Table 98 Parameters For Refreshing A Service Instance


Parameters Description
domainHome Path to BI domain home.
serviceKey Key for the service instance. It is a unique identifier for the
service instance.

For example,

refreshServiceInstance('/oraclehome/user_projects/domains/bi',
'mycompany.finance')

9.2.7 refreshDomainServiceInstances
This command refreshes all the service instances of the BI domain.
refreshDomainServiceInstances(domainHome)
Table 99 lists the parameters for this command.

Table 99 Parameter For Refreshing All Service Instances


Parameters Description
domainHome Path to BI domain home.

For example,

refreshDomainServiceInstances('/oraclehome/user_projects/domains/bi')

9-8 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Managing Service Instances

9.2.8 resetServiceInstance
This command removes all the customizations in a given service instance (similar to
an empty BAR state).
resetServiceInstance(domainHome, serviceKey)
Table 910 lists the parameters for this command.

Table 910 Parameters For Resetting A Service Instance


Parameters Description
domainHome Path to the BI domain home. For example, /oraclehome/user_
projects/domains/bi.
serviceKey Key for the service instance. It is a unique identifier for a service
instance. For example, 'ssi'.

Example - To use the resetServiceInstance command to remove customizations:


1. Configure Oracle Business Intelligence with an empty service instance (the same
as using an empty BAR file).
Note: The empty BAR file is here:
$BI_PRODUCT_
HOME/bi/bifoundation/admin/provisioning/oracle.bi.application.empty.bar
2. Deploy SampleAppLite to the BI domain and associate it with the service instance.
3. Make some customizations on top of the base BAR.
4. Use the resetServiceInstance command.
For example,
resetServiceInstance('/oraclehome/user_projects/domains/bi', 'ssi')

This removes the customizations created in step 3 and returns the service instance
to the state of step 2.

Managing Metadata and Working with Service Instances 9-9


Managing Service Instances

9-10 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
10
Configuring Connections to External Systems
10

This chapter describes how to configure connections to systems that are external to
[1]

Oracle Business Intelligence.


This chapter includes the following sections:
Configuring Email and Agents
Configuring for Actions with the Action Framework
Configuring Connections to the Marketing Content Server
Configuring Connections to Data Sources
As part of the process of configuring connections to external systems, you can
configure a database for the Oracle BI Scheduler. See "Configuring a Database for the
Oracle BI Scheduler" in Oracle Fusion Middleware Scheduling Jobs Guide for Oracle
Business Intelligence Enterprise Edition.

10.1 Configuring Email and Agents


You can use Fusion Middleware Control to configure common email settings that are
used by agents. Advanced configuration settings are described in Chapter 18,
"Configuring and Managing Agents."

10.1.1 Using Fusion Middleware Control to Configure Oracle BI Scheduler Email


Settings that Affect Agents
Before you begin this procedure, ensure that you are familiar with the information in
Section 8.3.1, "Using Fusion Middleware Control".
To use Fusion Middleware Control to configure Oracle BI Scheduler email settings
that affect agents:
1. Go to the Business Intelligence Overview page, as described in Section 8.2.2,
"Displaying Oracle Business Intelligence Pages in Fusion Middleware Control."
2. Display the Mail tab of the Configuration page as appropriate.
3. Click Lock and Edit to enable changes to be made.
4. Complete the elements using the descriptions in the help topic for the page. Click
the 'Help for this page' menu option to access the page-level help for the following
options:
SMTP Server
Port

Configuring Connections to External Systems 10-1


Configuring for Actions with the Action Framework

Display name of sender


This option is used in the SMTP From field as a meaningful substitution for
the sender's address. The default is Oracle Business Intelligence.
Email address of sender
This option specifies the email address on the SMTP Server that is used as the
sender's reply-to address for all mail sent from Oracle BI Scheduler. The initial
value is defaultuser@defaultmailserver.com, which you must change to reflect
a valid email address. Note that if you want to indicate that email recipients
need not reply, add no_reply@mycompany.com or do_not_
reply@mycompany.com to this field.
Username
Password
Confirm password
Number of retries upon failure
Maximum recipients
Addressing method To, Blind Copy Recipient (Bcc)
Connection Security
Specify CA certificate source
CA certificate directory
CA certificate file
SSL certificate verification depth
SSL cipher list
5. Click Apply, then click Activate Changes.
6. Return to the Business Intelligence Overview page and click Restart.
See Chapter 18, "Configuring and Managing Agents" for information about advanced
configuring settings for agents.
For information about corresponding configuration file elements, see Table C1,
" Performance Tab - Mapping Between User Interface Labels and Configuration File
Elements"

10.2 Configuring for Actions with the Action Framework


Users can create actions in the Oracle BI Presentation Services user interface. An action
is an operation or process that can be invoked explicitly by a user clicking an action
link. Actions can also be invoked automatically, as the final step of an agent.
You can configure for the use of actions in your organization. For a comprehensive
discussion of how to use the Action Framework to enable actions for external systems,
including a complete description of each configuration setting and detailed examples,
see Oracle Fusion Middleware Integrator's Guide for Oracle Business Intelligence Enterprise
Edition.

10.3 Configuring Connections to the Marketing Content Server


Oracle Marketing Segmentation handles segmentation, which involves dividing a
target audience into different segments given different criteria based on the subject

10-2 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Configuring Connections to Data Sources

areas. When a segment is ready, users create lists of the contacts and accounts that
satisfy the criteria for the segment. Users then specify whether to store the generated
lists on the file system, in a database, or on a specified Content Server.
For users to store the lists on a Content Server, you as the administrator must
configure the connection to the Content Server by specifying the appropriate URL and
other values in the instanceconfig.xml file.
To manually edit additional settings for the Marketing Content Server connection:
Use various elements in the instanceconfig.xml file to configure settings for the
connection to the Marketing Content Server.
1. Open the instanceconfig.xml file for editing, at:
BI_DOMAIN/config/fmwconfig/biconfig/OBIPS
For information, see Section A.1, "Configuration Files".
2. Locate the section in which you must add the elements that are described in the
following list:
URL: Specifies the address of the content server machine.
SocketTimeoutSec: Specifies the number of seconds that the socket waits for
the Content Server to respond while transferring records. The default value is
60. There is no minimum or maximum value.
FileSizeMB: Specifies the size in megabytes of files that are generated during
ListGeneration and inserted into the Content Server. The default is 10. The
minimum size is 1MB and the maximum size is 50MB.
3. Include the elements and their ancestor elements as appropriate, as shown in the
following example:
<ServerInstance>
<Marketing>
<ContentServer>
<URL>myhost.com:6666/st1b2rep/idcplg</URL>
<SocketTimeoutSec>120</SocketTimeoutSec>
<FileSizeMB>5</FileSizeMB>
</ContentServer>
</Marketing>
</ServerInstance>

You cannot specify values for user name and password in the instanceconfig.xml
file. Instead you specify values stored securely within the central credentials
wallet, along with all other user names and passwords.
4. Save your changes and close the file.
5. Restart Oracle Business Intelligence.

10.4 Configuring Connections to Data Sources


Connections to data sources are defined in the Oracle BI repository. Repository
developers use the Administration Tool to configure data source connections by
importing metadata and configuring connection pools. See "Importing Metadata and
Working with Data Sources" in Oracle Fusion Middleware Metadata Repository Builder's
Guide for Oracle Business Intelligence Enterprise Edition for more information.
You might need to update connection pool information in the repository during
migrations to production and other environments. You can use the Oracle BI Server

Configuring Connections to External Systems 10-3


Configuring Connections to Data Sources

XML API to automate these connection pool changes. See "Moving from Test to
Production Environments" in Oracle Fusion Middleware XML Schema Reference for Oracle
Business Intelligence Enterprise Edition for more information.

10-4 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
11
Configuring Presentation Setting Defaults
11

This chapter describes how to change default presentation settings in Oracle Business
[12]

Intelligence that administrators commonly change using Fusion Middleware Control.


Advanced configuration settings are described in Section 17.5, "Manually Changing
Presentation Settings."

11.1 Using Fusion Middleware Control to Change Presentation Setting


Defaults
Before you begin this procedure, ensure that you are familiar with the information in
Section 8.3.1, "Using Fusion Middleware Control."
To use Fusion Middleware Control to change presentation setting defaults:
1. Go to the Business Intelligence Overview page, as described in Section 8.2.2,
"Displaying Oracle Business Intelligence Pages in Fusion Middleware Control."
2. Display the Presentation tab of the Configuration page.
3. Click Lock and Edit to enable changes to be made.
4. Complete the elements using the descriptions in the help topic for the page. Click
the 'Help for this page ' menu option to access the page-level help for the
following options:
Show page tabs option
Show section headings option
Allow dashboard sections to be collapsible option
Pivot Tables show auto-preview option
5. Click Apply, then click Activate Changes.
6. Return to the Business Intelligence Overview page and click Restart.
See Chapter 17, "Configuring and Managing Analyses and Dashboards" for
information about advanced configuring settings for analyses and dashboards.
For information about corresponding configuration file elements, see Table C1,
" Performance Tab - Mapping Between User Interface Labels and Configuration File
Elements".

Configuring Presentation Setting Defaults 11-1


Using Fusion Middleware Control to Change Presentation Setting Defaults

11-2 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
12
Configuring Mapping and Spatial Information
12

This chapter describes how to configure mapping and spatial information for map
[13]

views in Oracle Business Intelligence. When you install Oracle Business Intelligence,
you install functionality for users to see maps that display data. Before users can see
maps in analyses and dashboards, you must understand the system requirements,
specify layers and maps, and configure the metadata, as described in this chapter.
This chapter includes the following sections:
What Are the System Requirements for Map Views?
Hardware Sizing and Deployment Strategy for Maps
Administering Maps
See Chapter 19, "Configuring Advanced Options for Mapping and Spatial
Information" for information about advanced configuration options for maps.

12.1 What Are the System Requirements for Map Views?


To include map views on dashboards, the system must include the following
components:
Oracle MapViewer, which is a J2EE service that serves as an engine for rendering
maps using spatial data managed by Oracle Spatial. MapViewer is closely
integrated with Oracle BI EE. MapViewer is installed as part of Oracle BI EE and
deployed in the same domain as Oracle BI EE on the web application server.
MapViewer provides services and tools that hide the complexity of spatial data
queries and cartographic rendering, while providing customizable options for
more advanced users. MapViewer is designed to integrate with Location-Based
services and applications.
For information, see Section 19.1, "Configuring MapViewer to Support Map
Views."
Spatial boundary data. NAVTEQ is one provider of this data to Oracle customers,
which can be downloaded from the Oracle Technology Network. This spatial data
and any other spatial metadata, including themes and styles, must be stored in an
Oracle Database to be accessed by Oracle MapViewer for display in map views.
Hosted maps. In Oracle BI EE, users can access hosted maps from the Oracle
eLocation service. Terms and conditions of use are located at the following URL:
http://elocation.oracle.com/elocation/legal.html
Oracle Database, version 10g or later, to store the spatial data.

Configuring Mapping and Spatial Information 12-1


What Are the System Requirements for Map Views?

Oracle Locator, which is a feature of Oracle Database (all editions) that provides
core location functionality needed by most customer applications.
If you use an Oracle Database as the Repository Creation Utility (RCU) database,
then you can use that same Oracle Database for spatial data also. See Oracle Fusion
Middleware Installation Guide for Oracle Business Intelligence for information.
(Optional) Oracle Spatial is an option for Oracle Database Enterprise Edition that
provides advanced spatial features to support high-end geographic information
systems (GIS) and location-based services (LBS) solutions. The Spatial option is
required only if you plan to make use of maps or features that require advanced
spatial capabilities that are not available with the Locator option. Additional
Oracle Spatial features include raster and 3D data management, spatial web
services, topology, network data modeling, resource description framework (RDF),
and semantic web capabilities.
Metadata of the mapping between Oracle BI EE data and spatial data, which can
be stored in a file system, in the Oracle BI Presentation Catalog.
Figure 121 shows the default architecture for map views when Oracle BI EE is
installed. You can store the data either in an Oracle Database or in other databases that
Oracle BI EE supports. See Figure 191 for a diagram of the preferred architecture for
map views.

Figure 121 Default Architecture for Map Views

When these pieces are in place, you administer the map using the Oracle BI
Presentation Services Administration page, as described in Section 12.3,

12-2 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Administering Maps

"Administering Maps."

12.2 Hardware Sizing and Deployment Strategy for Maps


Rendering map views is computationally more intensive than rendering tabular views,
due to the requirements to:
Query spatial data.
Create the polygons and shapes that correspond to geographical entities such as
countries and states.
Place the polygons and shapes on a background map.
Provide end-user interactivity such as the ability to pan and zoom, to adjust color
thresholds, and to show or hide formats.
Assess the extent of expected usage of map views at your organization including the
number of users that are expected to use map views, the amount of data to be
displayed on map views, and the amount of spatial data that is expected to be
displayed (such as only city boundaries or street level details). Based on this
assessment, decide on an appropriate hardware sizing and deployment strategy. Also
review the available documentation on best practices for achieving optimal
performance and scalability with your Oracle MapViewer deployment.

12.3 Administering Maps


Before content designers can create map views, you as the Oracle BI Administrator
must specify layers and maps and configure the metadata. This section discusses the
following:
Section 12.3.1, "Working with Maps and Layers"
Section 12.3.2, "Administration Page Functions"
Section 12.3.3, "Administering Maps Using Administration Pages"
Section 12.3.4, "Handling the Translation of Layers in Maps"

12.3.1 Working with Maps and Layers


The first step is to select the layers for use on maps. An administrator has configured
layers using the Map Builder tool of Oracle Spatial. You next select at least one map
from a list of those that an administrator has configured using the Map Builder tool of
Oracle Spatial. This map becomes the background on which the layers are applied.
You can optionally specify images for use with map formats. This section provides the
following information about maps and layers:
Section 12.3.1.1, "Associating Layers with Columns"
Section 12.3.1.2, "Ordering Layers on Maps"
Section 12.3.1.3, "Changes to Spatial Metadata Require Restart"

12.3.1.1 Associating Layers with Columns


After selecting layers and maps, you can associate certain layers with columns in the
Oracle Business Intelligence subject area folders. If the association between a column
and a layer is incorrect, then the layer cannot be displayed correctly on the map. The
association ensures that shape definitions can be found in the database for the column
values during map rendering. You must ensure that a shape geometry definition exists

Configuring Mapping and Spatial Information 12-3


Administering Maps

for each column value in the database. If a shape geometry definition does not exist for
a particular column value, then the shape cannot be shown on the map and might
inhibit user interactions on the map.
Shape lookup is based on the column values, and column-to-layer mapping is
independent of locale or language. Therefore, you must ensure that the spatial column
that is being associated with a layer does not itself have values that are affected by
locale or language. To ensure this association, do one of the following:
Model spatial columns as double columns in the business modeling layer, which is
the recommended method.
Create special spatial columns that have values that do not change across locale or
language. You must ensure that content designers are not confused seeing these
special columns in the Subject Areas pane when working with analyses.
If you decide to use double columns, then see Oracle Fusion Middleware Metadata
Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition for more
information on double columns. The advantages of using double columns are the
following:
You can provide code values (that is, descriptor IDs) for each shape definition and
at the same time show display values (that is, descriptor values) according to
locale or language.
Code values are passed only as layer key values for lookup.
You eliminate the need for the complex joining of various columns to uniquely
locate the shape. For example, a layer geometry table might contain multiple cities
with the name of London. To uniquely distinguish these cities, you might use a
pattern of Country_State_City, as in US_Kansas_London or Canada_Ontario_
London. The problem with this approach is that it might require three separate
columns to be grouped, joined by a delimiter (such as an underscore), and
associated with a layer. This association requires the content designer to select
three columns (Country, State, City) in the criteria to create a single layer.
A BI layer can be associated with multiple columns in multiple subject areas. You must
ensure that a layer is associated with at least one spatial column. If the layer
association is missing, then the map might not be updated when a user drills on the
mapped BI column. You can also have feature layers, which are layers that are not
associated with a BI column.

12.3.1.2 Ordering Layers on Maps


The ordering of map layers is very important. You must pay close attention to ensure
that users have a seamless experience while navigating on the map (that is, drilling
and zooming). In the Edit Background Map dialog, you assign each layer a minimum
and maximum zoom range. Given that the map zoom slider can slide only from
bottom to top vertically, the layers with lower minimum zoom levels are placed at the
bottom of the slider. Ensure that the layer grid on the Interactive BI Layers section of
the dialog follows a similar pattern, so that you place layers with lower minimum
zoom levels at the bottom of the list. Ensure the following:
That you sort the layers (by clicking the sort icon) before closing the dialog.
That BI layers are ordered higher than non-BI layers. If a non-BI layer is ordered
higher than any BI layers, then the non-BI layer is displayed on top of the lower BI
layers on the map, which prevents the BI layers from being interactive.
Layer ordering becomes irrelevant when the zoom ranges of layers do not intersect on
the scale. Ordering becomes very important when layers have a common minimum

12-4 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Administering Maps

and maximum zoom range. Use care to ensure that detailed layers are not hidden by
the aggregated layers during drilling or zooming operations.

Example 121 World Map with Three Layers


Suppose that a world map has three layers (Country, State, and City) and 15 zoom
levels defined on it. The Country layer has a minimum and maximum zoom range of
0-5, the State layer range is 6-10, and the City layer range is 11-15. As the user
navigates from the minimum to the maximum zoom level on the map, the layer order
(also known as the visual order) is displayed as Country, State, and City.
Figure 122 shows the Edit Background Map dialog with the Interactive BI Layers
section specified for this example. Reading from bottom to top, you see the layer order
in that section as Country, State, and City.

Figure 122 Edit Background Map Dialog with No Intersection

Example 122 World Map with Common Levels


Consider the same world map with layers that have common zoom ranges. Suppose
that the user zooms to level 4 on the map that corresponds to the Edit Background
Map dialog that is shown in Figure 123. Notice that all three layers include zoom
level 4.

Configuring Mapping and Spatial Information 12-5


Administering Maps

Figure 123 Edit Background Map Dialog with Intersection

The layer ordering at zoom level 4 is unclear, because multiple layers can be shown.
Because of the layer order that is specified in the Interactive BI Layers section of the
dialog, the map renders with the following order at zoom level 4: Country, Sate, and
City (reading from bottom to top).
If the layers are not ordered properly in the dialog, then you can re-order layers by
clicking the Move Down and Move Up buttons on the zoom grid of the dialog, or by
clicking the Sort Layers by Zoom Level button.
See Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise
Edition for more information about layers.

12.3.1.3 Changes to Spatial Metadata Require Restart


An administrator can edit the spatial metadata that is stored in the Oracle Database
and accessed by MapViewer. For example, an administrator can add a new layer.
These edits are not visible on the Oracle BI Presentation Services Administration pages
for managing maps until MapViewer is restarted and so refreshed with the latest
updates.

12.3.2 Administration Page Functions


The Oracle BI Presentation Services Administration page provides the Manage Map
Data link. This link displays the Manage Map Data page, where you can manage the
logical and display versions of the data from various physical data sources. This
defines the layers that content designers use when creating map views. The data that
is available for managing maps and data is stored in Oracle Database as part of
MapViewer.
Using this page, you provide:
Logical names to prevent any existing BI column mappings and map analyses
from breaking because of changes to the physical data or to the data source.
Display names so that the geographic data is meaningful to end users.

12-6 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Administering Maps

12.3.3 Administering Maps Using Administration Pages


This section assumes that you installed Oracle BI Enterprise Edition and that Oracle
MapViewer was automatically configured and deployed. For information on
MapViewer, see Oracle Fusion Middleware User's Guide for Oracle MapViewer.
To administer maps using Administration pages:
1. Sign in to Oracle Business Intelligence.
Ensure that you have been granted the Access to Administration and Manage Map
Data privileges.
2. In the global header, click Administration.
3. Click the Manage Map Data link to display the Manage Map Data page.
4. Click the Layers tab.
5. Click the Import Layers button to display the Import Layers dialog.
6. In the dialog, select the connection and the layers that are needed for zooming and
drilling. (This tab is not prepopulated by other selections on the Administration
pages. You can use any layers or images with any map.)
Click OK when you have finished selecting layers that are appropriate for the
subject area with which you are working.
7. Back on the Layers tab, select a layer, then click the Edit Layer button to display
the Edit Layer dialog in which you associate layers with attribute columns so that
you can display BI data in the map view.
Click OK when you have finished editing the layer.
You use this tab to associate layers with BI data. If you use the City column in
multiple subject areas, then you must associate it with a layer for each subject area.
8. Click the Background Maps tab, then click the Import Background Maps button
to display the Import Background Map dialog.
9. In the dialog, select the connection and the main maps to use.
The connection that you select for the main map can be different from the
connection for the layers or images.
Click OK when you have finished selecting main maps.
10. Back on the Background Maps tab, select a map, then click the Edit Background
Map button to display the Edit Background Map dialog in which you name the
map and specify the order of layers and their zoom levels.
Click OK when you have finished editing the map.
11. Optionally, click the Images tab, then click the Import Images button to display
the Import Images dialog. You can import images if you plan to use them as a
format on maps.
12. In the dialog, select the connection and the images to use.

Click OK when you have finished selecting images.


13. Click Back when you have finished working with the Administration page. Your
changes are saved automatically.
After you have specified background maps, layers, and zoom levels, MapViewer
creates a static image for a map using this information. Then MapViewer sends that

Configuring Mapping and Spatial Information 12-7


Administering Maps

image for rendering in the browser for use by content designers and end users in map
views.

12.3.4 Handling the Translation of Layers in Maps


You can use the functionality of MapViewer to label the features of a theme (called a
layer for maps in Oracle BI EE) using a specific language or locale. To configure these
translated labels for maps, use the information that is provided in Oracle Fusion
Middleware User's Guide for Oracle MapViewer.

12-8 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
13
Configuring Time Zones
13

This chapter describes how to configure time zones for Oracle Business Intelligence.
[14]

This chapter includes the following sections:


Why and Where Are Time Zones Used?
Setting Time Zones
What is the Precedence Order for Time Zones
Where Are Time Zone Specifications Stored?
Description of Time Zone Settings
Example: Configuration File Settings for Specifying the Time Zone

13.1 Why and Where Are Time Zones Used?


Time zones are used throughout Oracle Business Intelligence for a variety of purposes.
A time stamp can indicate when an object was changed, and users can specify a time
for an agent to run. Users often are most comfortable working in their local time zones.
As the administrator, you can configure the preferred time zones for users for various
components.
Before you begin to set preferred time zones, see Table 131 for information about
where time zones are used.

Table 131 Time Zone Usage


Type Description
Oracle BI Presentation Services If you have users in time zones that are different from
the zone for Presentation Services, then you as the
administrator can specify the time stamps that those
users see in Oracle Business Intelligence. For example,
suppose the server is located in the Pacific time zone in
the United States. You can specify that users on the east
coast of the United States see time stamps that are
displayed in Eastern Standard Time.
If you make no time zone settings and if a user does not
specify a preferred time zone using the My Account
dialog, then that user sees time displayed according to
the local time zone for Presentation Services.
For information about how users specify their preferred
time zones, see Oracle Fusion Middleware User's Guide for
Oracle Business Intelligence Enterprise Edition.

Configuring Time Zones 13-1


Setting Time Zones

Table 131 (Cont.) Time Zone Usage


Type Description
Data from the database The Oracle BI Administrator specifies the time zone for
the data that is retrieved from the database.
If you make no time zone settings, then users see the
time stamp data in the time zone of the original data as
set by the Oracle BI Administrator.
Content that is displayed in Oracle Users who create analyses can specify the time zone
Business Intelligence that is displayed in their analyses and dashboard
prompts. This specification overrides those made by
you as the administrator and by end users if they have
previously used the column in their queries and have
set the time zone.
If the specified display time zone supports daylight
saving time, then the timestamp values that are
displayed are automatically adjusted for daylight
saving time.
General time stamps that indicate End users can specify the time zone for many general
when events happen stamps including the following ones:
The scheduled time of agents.
The generated time of alerts or analyses.
The time on which objects in the Oracle BI
Presentation Catalog are created, modified, and
accessed.
Log files Log files contain time stamps for various activities.

13.2 Setting Time Zones


Use the following procedure to set time zones for users.
To set preferred time zones for users:
1. Determine the time zone that is set for the server on which Presentation Services is
running.
2. Use elements in the Presentation Services configuration file (instanceconfig.xml) or
use session variables. The instanceconfig.xml file is located in:
BI_DOMAIN/config/fmwconfig/biconfig/OBIPS
Consult the following for more information:
See Table 132 for information about the precedence order for time zones.
See Table 133 for descriptions of the session variables and elements.
See Section 13.6, "Example: Configuration File Settings for Specifying the Time
Zone."
See Oracle Fusion Middleware User's Guide for Oracle Business Intelligence
Enterprise Edition for complete information about session variables.
3. Encourage end users to specify their preferred time zones using the My Account
dialog.
4. Encourage users who create analyses to do the following to set the time stamps for
their analyses:
a. Use the Data Format tab of the Column Properties dialog to specify the time
zone that is displayed in the columns of their analyses.

13-2 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Where Are Time Zone Specifications Stored?

b. Use the Time Zone dialog to set the time zone that is displayed in dashboard
prompts.

13.3 What is the Precedence Order for Time Zones


The actual time zone in which various types of content are displayed follows a
precedence order that Table 132 describes. In the table, the items with lower numbers
override those with higher numbers. For example, Item 1 takes precedence over Item
2.

Table 132 Precedence Order for Time Zones


Time Zone For Determined By
Data 1. The setting of the DATA_TZ session variable.
2. The setting of the DefaultDataOffset element in
the instanceconfig.xml file.
3. The time zone of the original data as set by the
Oracle BI Administrator (because the time zone is
unknown for Presentation Services).
Data display 1. The setting that a content designer makes.
2. The setting of the DATA_DISPLAY_TZ session
variable.
3. The setting of the DefaultDataDisplay element in
the instanceconfig.xml file.
4. "User-Preferred Time Zone"
General time stamps (not including 1. "User-Preferred Time Zone"
column data and log files)
2. The time zone for Oracle BI Presentation Services.
Log file information 1. The setting of the Logging element in the
instanceconfig.xml file.
2. The time zone for Presentation Services.

13.3.1 User-Preferred Time Zone


The user-preferred time zone is determined by the following:
The specification that a user makes in the My Account dialog. Users can select a
time zone in which they prefer to view content.
For information about setting the time zone preference on the My Account dialog:
Preferences tab, see Oracle Fusion Middleware User's Guide for Oracle Business
Intelligence Enterprise Edition.
The setting of the TIMEZONE session variable.
The setting of the DefaultUserPreferred element in the instanceconfig.xml file.

13.4 Where Are Time Zone Specifications Stored?


Whenever a time zone specification is displayed in a list or as the value of a session
variable or element in the instanceconfig.xml file, that specification originates from the
TimeZones.xml file, located in:
orahome/bi/bifoundation/timezone

Configuring Time Zones 13-3


Description of Time Zone Settings

The TimeZones.xml file contains nearly all time zones from around the world. You
need not add zones to this file, but you can edit this file if you care to. You can delete
those zones that users in your organization do not use.

13.4.1 Specifying Time Zone Values


Various editors show the ampersand that appears in time zone values in one of two
ways: either the ampersand character itself or its escape sequence. Use care when
entering a time zone value, as follows:
When you use the ampersand in the value of a session variable, include the
ampersand character (&) in the value, such as "Pacific Time (US & Canada);
Tijuana".
When you use the ampersand in the value of an element in the Oracle BI
Presentation Services configuration file (instanceconfig.xml), include the escape
sequence for the ampersand in the value, such as "Pacific Time (US &amp;
Canada); Tijuana"

13.5 Description of Time Zone Settings


Table 133 describes the session variables and the elements in the instanceconfig.xml
file with which you set time zones. When you include elements in the
instanceconfig.xml file, you specify the time zone that all users see. When you use
session variables, you can specify a different time zone for each user. If you use session
variables and you specify values for the appropriate elements in the
instanceconfig.xml file, then the values of the session variables override the settings in
the instanceconfig.xml file.

Note: Certain system session variables such as, USER or ROLES,


cannot be overridden by request variables. Other system session
variables, such as DATA_TZ and DATA_DISPLAY_TZ (Timezone),
can be overridden if configured in the Oracle BI Administration Tool.
For more information, see "Working with Repository Variables" in
Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle
Business Intelligence Enterprise Edition.

13-4 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Description of Time Zone Settings

Table 133 Time Zone Settings


Session
Element Variable Description Value
DefaultDataOffset DATA_TZ The time zone offset of An offset that indicates
the original data. To the number of hours
enable the time zone to away from GMT time.
be converted so that For example:
users see the appropriate
"GMT-05:00" or "-300",
zone, you must set the
which means minus 5
value of this element or
hours.
variable.
If you do not set this
option, then no time
zone conversion occurs
because the value is
"unknown".
For example, suppose
you want to convert to
Eastern Standard Time
(EST), which is
Greenwich Mean Time
(GMT) - 5. You must
specify this value to
enable the conversion to
EST.
DefaultDataDisplay DATA_ Specifies the time zone to One of the time zones
DISPLAY_TZ use for displaying data. that are specified in the
TimeZones.xml file.
If you do not set this
option, then the value is See Section 13.4.1,
the "User-Preferred Time "Specifying Time Zone
Zone". Values."
DefaultUserPreferred TIMEZONE Specifies the users' One of the time zones
default preferred time that are specified in the
zone before they select TimeZones.xml file.
their own in the My
See Section 13.4.1,
Account dialog.
"Specifying Time Zone
If you do not set this Values."
option, then the value is
the local time zone from
Oracle BI Presentation
Services.
Logging Not The time zone of the time One of the time zones
applicable stamps that appear in log that are specified in the
files that are generated TimeZones.xml file.
by Presentation Services.
See Section 13.4.1,
If you do not set this "Specifying Time Zone
option, then the value is Values."
the local time zone from
Presentation Services
TimeZone Not The parent element for Not applicable
applicable the elements that modify
the preferred time zone.
A child of the
ServerInstance element.

Configuring Time Zones 13-5


Example: Configuration File Settings for Specifying the Time Zone

13.6 Example: Configuration File Settings for Specifying the Time Zone
The following shows a sample section of the instanceconfig.xml file in which the
TimeZone element has been added.
<TimeZone>
<DefaultDataOffset>0</DefaultDataOffset>
<Logging>(GMT-08:00) Pacific Time (US &amp; Canada); Tijuana</Logging>
<DefaultUserPreferred>(GMT-08:00) Pacific Time (US &amp; Canada);
Tijuana</DefaultUserPreferred>
<DefaultDataDisplay>(GMT-06:00) Central Time (US &amp; Canada);
Tijuana</DefaultDataDisplay>
</TimeZone>

13-6 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
14
Localizing Oracle Business Intelligence
14

This chapter describes how to configure Oracle Business Intelligence for deployment
[15]

in one or more language environments other than English. Users can easily and
dynamically change their language and locale preferences. When users select a
language, they see many elements in that language. These elements include user
interface components, metadata, messages, and help files.
This chapter includes the following sections:
What Is Localization?
Localizing Oracle BI Presentation Services
Setting the Current Locale in Catalog Manager
Setting the Current Locale in the Oracle BI Server
Localizing Metadata Names in the Repository
Supporting Multilingual Data

14.1 What Is Localization?


In this chapter, localization refers to the process of adapting the Oracle Business
Intelligence deployment to a particular language. If your users speak languages other
than English, then use the information in this chapter to adapt your deployment to
support multiple languages.
For information about supported languages, see Section 1.9, "System Requirements
and Certification."

14.1.1 What Components Are Translated?


The following list outlines which components of Oracle Business Intelligence are
translated into languages other than English:
Installer
Web user interface
Job Manager interface of the Oracle BI Scheduler
Catalog Manager
Oracle BI Presentation Services messages:
error
warning

Localizing Oracle Business Intelligence 14-1


What Is Localization?

information
Oracle BI Server functions:
DayName
MonthName

Note: If a query is issued using the DayName or MonthName


function, but the function is not shipped to a back-end database, then
the day or month name is returned in the localized language but the
column name remains in English (or might be affected by other
localization controls). As an example of this situation, if the LOCALE
parameter is set for German, the MonthName query returns the string
"Mai" but the column header remains "Name of Month."

Oracle BI Server and Oracle BI Scheduler messages:


error
warning
information
Log files:
nqserver.log for Oracle BI Server
nqquery.log for Oracle BI Server
If Clustering is enabled, nQCluster.log for Oracle BI Server Cluster
Metadata:
Dashboards and analyses (Oracle BI Presentation Catalog)
Presentation table and column names (.rpd file)
Oracle BI Administration Tool interface
ODBC setup
The following list outlines which components of Oracle Business Intelligence are not
localized:
ODBC client tools:
nqcmd (UNIX)
nqcmd.exe (Windows)
nqclient.exe (Windows)
Numerous Oracle Fusion Middleware components, such as Oracle WebLogic Server
Administration Console and Fusion Middleware Control, are translated. See Oracle
Fusion Middleware documentation for information.

14.1.2 Tasks for Localizing Oracle Business Intelligence Components


As the administrator, you perform various tasks to localize the components of Oracle
Business Intelligence, as described in the following sections:
Section 14.2, "Localizing Oracle BI Presentation Services"
Section 14.4, "Setting the Current Locale in the Oracle BI Server"

14-2 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Localizing Oracle BI Presentation Services

Section 14.5, "Localizing Metadata Names in the Repository"


Section 14.6, "Supporting Multilingual Data"

14.2 Localizing Oracle BI Presentation Services


As the administrator, you perform various tasks to localize Oracle BI Presentation
Services, as described in the following sections:
Section 14.2.1, "Localizing the User Interface for Oracle BI Presentation Services"
Section 14.2.2, "Localizing Oracle BI Presentation Catalog Captions"
Section 14.2.3, "Tip for Arabic and Hebrew in Mozilla Firefox Browsers"

14.2.1 Localizing the User Interface for Oracle BI Presentation Services


You can localize the user interface for Oracle BI Presentation Services, if your users
speak languages other than English. Users can select a language on the sign-in page
for Oracle BI EE, and many elements of the interface are automatically displayed in the
appropriate language. After signing in, users can change the language setting on the
Preferences tab of the My Account dialog.
The user's setting is stored in the WEBLANGUAGE session variable. For the Oracle BI
Presentation Services user interface, WEBLANGUAGE is set when a user selects a
language on the sign-in page.

Note: For Oracle BI Applications, WEBLANGUAGE is set to the


language of the user's browser when a user logs in for the first time.
For example, if a user with a browser language set to French logs in to
Oracle BI Applications for the first time, then the value for
WEBLANGUAGE is French, and the metadata is translated to French.

As the administrator, you perform various tasks to localize other elements of the user
interface for Oracle BI Presentation Services, as described in the following sections:
Section 14.2.1.1, "Understanding the Directory Structure for Localizing
Presentation Services"
Section 14.2.1.2, "Localizing Messages for Users' Preferred Currency"
Section 14.2.1.3, "Specifying the Default Language for the Sign-In Page"
Section 14.2.1.4, "Configuring the Languages and Locales for the Sign-In Page"
Section 14.2.1.6, "Specifying the Language in the URL"

14.2.1.1 Understanding the Directory Structure for Localizing Presentation


Services
Oracle BI EE is installed with many files that control elements in the user interface and
messages. These files are installed in the messages and pages subdirectories of the
ORACLE_HOME/bi/bifoundation/web/msgdb directory. To localize these elements
and messages, you copy those files to the l_xx subdirectories in SDD/service_
instances/service1/metadata/content/msgdb/l_xx
where SDD is the Singleton Data Directory (for more information, see Section 1.4, "Key
Directories in Oracle Business Intelligence"), and _xx indicates the language extension.

Localizing Oracle Business Intelligence 14-3


Localizing Oracle BI Presentation Services

After you have copied the files, you can modify their contents as appropriate for the
language that corresponds to the subdirectory in which you have copied them.

14.2.1.2 Localizing Messages for Users' Preferred Currency


Section 15.2.1, "Defining User-Preferred Currency Options Using a Static Mapping"
provides a procedure for working with users' preferred currencies. Use the following
procedure to localize the messages that are associated with a preferred currency.
To localize the messages that are associated with each users' preferred currency:
1. Go to the SDD/service_instances/service1/metadata/content/msgdb/l_xx
directory, where xx is the language extension for the language in which you are
specifying preferred currencies.
Where SDD is the Singleton Data Directory for example, DOMAIN_HOME/bidata
(for more information, see Section 1.4, "Key Directories in Oracle Business
Intelligence").
2. In the directory, create a subdirectory called customMessages.
3. In the directory, create a file in XML format, with the name of
usercurrencymessages.xml.
4. Add entries such as the following one to this file for the language that corresponds
to the directory in which you are working. The following example includes two
messages: kmsgMyCurrency1 and kmsgMyCurrency2
<?xml version="1.0" encoding="utf-8"?>
<WebMessageTables xmlns:sawm="com.siebel.analytics.web/message/v1">
<WebMessageTable system="CurrencyDisplay" table="Messages" code="false">
<WebMessage name="kmsgMyCurrency1"><TEXT>My Currency Text
1</TEXT></WebMessage>
<WebMessage name="kmsgMyCurrency2"><TEXT>My Currency Text
2</TEXT></WebMessage>
</WebMessageTable>
</WebMessageTables>

5. Edit the file to specify displayMessage="kmsgMyCurrency1" to use this message.


6. Repeat Steps 1 through 5 for each language for which you must localize these
messages.
7. Restart the service for Oracle BI Presentation Services.
In Oracle BI EE, the appropriate localized text is displayed to the user. In this example,
the text is My Currency Text 1.

14.2.1.3 Specifying the Default Language for the Sign-In Page


The default language in which the Presentation Services sign-in page is displayed is
obtained from the user's client browser settings. The following procedure explains
how to change the language.

Note: The following procedure uses Internet Explorer 7.0 as an


example. If you are using a different browser, then make the necessary
substitutions.

To change the default language on a user's login screen in Internet Explorer:


1. In Internet Explorer, from the Tools menu, select Internet Options.

14-4 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Localizing Oracle BI Presentation Services

The Internet Options dialog is displayed.


2. Click Languages.
The Language Preference dialog is displayed.
Installed languages are displayed in the Language list. The language at the top of
the list is used as the default language.
3. If the desired language is not installed on the browser, then add it.
4. Use the Move Up and Move Down buttons to position the desired language at the
top of the list.
5. Restart the browser and sign into Presentation Services.
The default language likely matches the language in the browser's Language list.

Note: If a user does not select a different language from the list on
the sign-in page, then the setting for the User Interface Language in
the user's My Account dialog determines the language in which the
user interface is displayed.

14.2.1.4 Configuring the Languages and Locales for the Sign-In Page
You can configure the languages and locales that are available to users on the sign-in
page. This ability is helpful for limiting the number of languages and locales that users
can access. You use the AllowedLanguages and AllowedLocales elements in the
instanceconfig.xml file to specify the available languages and locales.
To manually configure the languages and locales that are available:
1. Open the instanceconfig.xml file for editing, located in:
BI_DOMAIN/config/fmwconfig/biconfig/OBIPS
See Section A.1, "Configuration Files"
2. Locate the ServerInstance section, in which you must add the following elements:
AllowedLanguages Specifies the languages that are available for selection,
as a comma-delimited list. You can specify a list of the following identifiers,
which are ISO 639 language codes:
ar
es
da
de
el
en
es
fi
fr
he
hr
hu
it
ja
ko
nl
no
pl

Localizing Oracle Business Intelligence 14-5


Localizing Oracle BI Presentation Services

pt
pt-BR
ro
ru
sk
sv
th
tr
zh-CN
zh-TW
AllowedLocales Specifies the locales that are available for selection, as a
comma-delimited list. You can specify any definition from the
localedefinitions.xml file in the ORACLE_
HOME/bi/bifoundation/web/display directory. You specify the locales using
ISO 639 language codes followed by ISO 3166 country codes. Examples
include fr-fr and fr-ca.
3. Include the elements and their ancestor elements as appropriate, as shown in the
following example:
<ServerInstance>
<Localization>
<AllowedLanguages>en,fr,pt-BR</AllowedLanguages>
<AllowedLocales>en-ca,en-us</AllowedLocales>
</Localization>
</ServerInstance>

4. Save your changes and close the file.


5. Restart Oracle Business Intelligence.

14.2.1.5 Specifying the Scaling of Numbers in Performance Tiles


In Presentation Services, you can use performance tiles to focus attention on a single
piece of high-level aggregate data. The tile can include a number such 1,000,000 or you
can specify to "compress" or "scale" the value with an indicator such as 1M, for
example.
To scale the number, Presentation Services searches for the scaling factors that the
current locale allows, processes the number, and appends the indicator value. If no
scaling factors are defined for the current locale, then no scaling is applied. Because
the scaling of numbers differs by language, you can manually edit the
localedefinitions.xml file to control the scaling, as described in the following
procedure.
To specify the scaling of numbers:
1. In a text editor, open the localedefinitions.xml file in the directory:
ORACLE_HOME/bi/bifoundation/web/display
2. In the file, add a new property for "scaleFactors" and enter values appropriate to
your locale.
The following shows values for an English locale:
<localeDefinition name="en">
<!-- existing data -->
<property name="scaleFactors">
<property name="thousand">K</property>
<property name="million">M</property>

14-6 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Localizing Oracle BI Presentation Services

<property name="billion">B</property>
<property name="trillion">T</property>
<property name="quadrillion">Q</property>
<property name="quintillion">Qu</property>
<property name="sextillion">S</property>
<property name="septillion">Sp</property>
<property name="octillion">O</property>
<property name="nonillion">N</property>
<property name="decillion">D</property>
<property name="undecillion">UD</property>
<property name="duodecillion">DD</property>
</property>
</localeDefinition>

The following shows values for an Indian locale:


<localeDefinition name="en-in" basedOn="en">
<!-- english - india -->
<!-- existing data -->
<property name="scaleFactors">
<property name="thousand">K</property>
<property name="hundred-thousand">L</property>
<property name="ten-million">Cr</property>
</property>
</localeDefinition>

3. Save your changes and close the file.


4. Restart Presentation Services.
For more information, see "Editing Performance Tile Views" in Oracle Fusion
Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

14.2.1.6 Specifying the Language in the URL


When users start Oracle BI EE by displaying the sign-in page, they can select the
language as part of the sign-in process. They can also select a language on the
Preferences tab of the My Account dialog.
If you provide users with a URL with which they can display a dashboard or other
page of the application, then you can define a URL parameter as a profile attribute.
Doing so dynamically sets the language of the dashboards and analyses to be
consistent with the application's language setting.
For operational applications, symbolic URLs embed dashboards and analyses in the
integrated environment. For Oracle BI Presentation Services, the URL parameter Lang
designates the language that the web page renders.
The Lang parameter can be included in the symbolic URL that is defined in the
operational application to connect to Oracle Business Intelligence. The Lang parameter
is defined as a profile attribute, but when the symbolic URL is constructed at runtime,
the value is set as the profile attribute LanguageCode. Table 141 provides examples of
the parameter settings in the Symbolic URL parameters applet, including Lang.
For example, the following URL displays the sign-in page in French.
http://Server_Name:port_number/analytics/saw.dll?Dashboard&Lang=fr

Localizing Oracle Business Intelligence 14-7


Localizing Oracle BI Presentation Services

Table 141 Example of Settings in the Symbolic URL Parameters Applet


Name Type Path Argument Value Append Sequence #
Cmd Constant Go Y 1
Path Constant /shared/Sales/Pipeline/Overvi Y 2
ew/Top 10 Deals
nQUser Command UseLoginId Y 3
nQPassword Command UseLoginPassword Y 4
PostRequest Command PostRequest Y 5
Lang Profile LanguageCode Y 6
Attribute

14.2.2 Localizing Oracle BI Presentation Catalog Captions


The Oracle BI Presentation Catalog stores objects that users create, such as analyses
and dashboards. Text strings hold the names and descriptions of these objects. If you
must localize text strings for the objects, then you can export the text strings from the
catalog so that they can be translated. You then expose the strings when translation is
complete.
This section describes the steps in the process of localizing captions:
Section 14.2.2.1, "Step 1: Understanding the Export Process"
Section 14.2.2.2, "Step 2: Exporting Text Strings in the Catalog"
Section 14.2.2.3, "Step 3: Editing Exported Strings in XML Files"
Section 14.2.2.4, "Step 4: Handling Duplicate Exported Text Strings"
Section 14.2.2.5, "Step 5: Exposing Text Strings in the Catalog"

14.2.2.1 Step 1: Understanding the Export Process


The export process creates one XML file for every first-level subfolder in the shared
folder, in the format foldernamecaptions.xml, where foldername is the name of the
subfolder in the shared folder. Each XML file contains the text strings for all content in
the corresponding first-level folder and its subfolders.
For example, if the shared folder in the Oracle BI Presentation Catalog contains the
first-level folders Marketing, Service, and Sales, then the export process creates three
XML files:
marketingcaptions.xml
salescaptions.xml
servicecaptions.xml
After the content is translated, you place these folders in their corresponding location
in the following directory:
SDD/service_instances/service1/metadata/content/msgdb/l_xx/captions
Where SDD is the Singleton Data Directory for example, DOMAIN_HOME/bidata (for
more information, see Section 1.4, "Key Directories in Oracle Business Intelligence").
The export process not only generates new XML files, but the process also modifies the
catalog, inserting the appropriate message ID for each object. Presentation Services
uses those message IDs to locate the newly translated text.

14-8 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Localizing Oracle BI Presentation Services

Note that an error may occur when you export a folder whose name includes
supplementary (extended Unicode) characters.

14.2.2.2 Step 2: Exporting Text Strings in the Catalog


The following procedure describes how to export text strings in the catalog.
To export text strings in the catalog:
1. Back up the catalog before exporting from it.
Ensure that you run the export utility against the actual catalog, not against a copy
of the catalog, because the export utility changes the properties of the objects in the
catalog against which it runs.
2. In Catalog Manager, open the catalog in offline mode, because you might lack
permission to modify all objects in online mode.
3. Select the folder that contains the strings to export. The utility runs against the
files in that folder and all its subfolders.
For example, the title (Another Report) in the analysis that is shown in Figure 141
can be exported for translation.

Figure 141 Title in an Analysis for Export and Translation

4. From the Tools menu, select Export Captions.


5. Click Browse to select the location in which to write the output file, then click OK.
6. To export only new text strings and those that have been changed since the last
export, select Only export new or changed strings.
7. To exclude the Description properties from the export, select Exclude
Descriptions.
8. Click OK.

Localizing Oracle Business Intelligence 14-9


Localizing Oracle BI Presentation Services

The export process might take several minutes.

14.2.2.3 Step 3: Editing Exported Strings in XML Files


When the export process is complete, deliver the output XML file to the localization
team.
When editing XML files, use an editor that is designed for XML files. Ensure that you
follow the encoding that is specified at the top of the XML file and that you escape
special characters as appropriate. You and the localization team are responsible for
resolving any errors in the translated text strings. Consider that the contents of the
catalog are updated whenever objects are added, deleted, or modified.
You can make a copy of every output file for each language to be translated.
Figure 142 shows an extract from an exported caption XML file before translation.
The file is named myfoldercaptions.xml. Figure 143 shows an extract from the file
after translation. The file is named myfoldercaptions_fr.xml.

Figure 142 Caption XML File Before Translation

Figure 143 Caption XML File After Translation

14.2.2.4 Step 4: Handling Duplicate Exported Text Strings


You might encounter an issue of having duplicate exported text strings from the
catalog. This situation arises when the Export Captions utility is run simultaneously

14-10 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Localizing Oracle BI Presentation Services

by multiple users or if the same user runs the utility twice in less than one minute. The
following procedure describes how to address duplicate captions.
To handle duplicate exported text strings:
1. Run the Export Captions utility, as described in Section 14.2.2.2, "Step 2: Exporting
Text Strings in the Catalog."
2. In Catalog Manager, with the catalog still open in offline mode, select the folder
that contains the strings to export.
3. From the Tools menu, select Export Captions.
4. Click Browse to select the location in which to write the output file, then click OK.
5. In the "What to do with duplicate captions" section, select one of the following
options:
Create unique IDs even for identical strings Specifies to create a unique
ID for each instance of a string, even if the string is duplicated many times in
the catalog. For example, suppose that a catalog includes the "Hello" string
1000 times. Use this option to specify that rather than generating one unique
ID and translating the string only once, you want to instead generate 1000
unique IDs and translate the string 1000 times.
No, use the same ID for all identical strings Specifies to create an ID for a
string and use that same ID for all instances of that string. For example,
suppose that a catalog includes the "Hello" string 1000 times. Use this option
to specify that you want to generate one unique ID and translate the string
only once, instead of generating 1000 unique IDs and translating the string
1000 times.
6. Click OK.
Consider the following webmessages.xml file, which contains duplicate captions:
<WebMessageTable system="catalog" type="folder" path="/shared/example/A">
<WebMessage name="kcap12790830_5" use="Caption" status="new">
<TEXT>A Really Good Report</TEXT>
</WebMessage>
</WebMessageTable>
<WebMessageTable system="catalog" type="folder" path="/shared/example/B">
<WebMessage name="kcap12790830_5" use="Caption" status="new">
<TEXT>I like this report</TEXT>
</WebMessage>
</WebMessageTable>
<WebMessageTable system="catalog" type="folder" path="/shared/example/Copy of A">
<WebMessage name="kcap12790830_5" use="Caption" status="new">
<TEXT>A Really Good Report</TEXT>
</WebMessage>
</WebMessageTable>

In this example file, Object B has an invalid duplicate message ID. Object Copy of A
has a valid but duplicate message ID. You can make the following selections in the
Export Captions dialog:
Selecting Leave alone makes no changes to the contents of the file.
Selecting Remove IDs generates new and unique IDs for both Object B and Object
Copy of A.
Selecting Remove texts generates a new and unique ID for Object B and deletes
the WebMessage element for Object Copy of A. While this option generally
ensures fewer messages to translate, keep in mind that you now see two objects

Localizing Oracle Business Intelligence 14-11


Localizing Oracle BI Presentation Services

with the same name in a directory listing of the catalog in Presentation Services
and in Catalog Manager.

14.2.2.5 Step 5: Exposing Text Strings in the Catalog


After you have exported the text strings for the catalog, you must expose them for
users.
To expose catalog text strings:
1. Place the translated XML files into their corresponding location in the following
directory and restart Presentation Services:
SDD/service_instances/service1/metadata/content/msgdb/l_xx/captions
where SDD is the singleton data directory (see Section 1.4, "Key Directories in
Oracle Business Intelligence")
where xx is the language extension.
For example:
DOMAIN_HOME/bidata/service_
instances/service1/metadata/content/msgdb/l_en/captions/myfoldercaptions_
fr.xml
Other examples of language extensions include cs for Czech and de for German.

Note: The SDD/service_


instances/service1/metadata/content/msgdb/l_xx/captions
directory exists only if Oracle Business Intelligence Applications have
been installed. If it does not exist, then you must create it.
Where SDD is the Singleton Data Directory for example, DOMAIN_
HOME/bidata (for more information, see Section 1.4, "Key Directories
in Oracle Business Intelligence").

2. The export process not only generates new XML files, but the process also
modifies the catalog, inserting the appropriate message ID for each object. After
placing the translated XML files in the directory as specified in Step 1, place the
modified catalog in either its default location or in the appropriate location that
the system now uses. See Section 1.4, "Key Directories in Oracle Business
Intelligence" for information.
3. Sign into Oracle Business Intelligence and select the appropriate language, such as
French.
4. Display the translated content.
For example, display the translated title in an analysis, as shown in Figure 144.

14-12 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Setting the Current Locale in Catalog Manager

Figure 144 Title in an Analysis After Export and Translation

To move translated captions from a development environment to a production


environment:
If the caption file:
Does not exist in the production environment, then simply copy it from the
development environment to the production environment.
Does exist in the production environment, first make a backup copy of the
existing file. Then open the caption file in the production environment in a text
editor or XML editing tool and manually (and very carefully) insert the
changes that were made in the development environment.

14.2.3 Tip for Arabic and Hebrew in Mozilla Firefox Browsers


By default, scroll bars are displayed on the right side of the Mozilla Firefox browser. If
you are using the Arabic or Hebrew languages, then it is not appropriate to have the
scroll bars on the right side. You can change the browser settings in Firefox such that
the scroll bars are displayed on the left side.
For information about changing the layout.scrollbar.side setting, see the Firefox
documentation.

14.3 Setting the Current Locale in Catalog Manager


When you use Catalog Manager, you can specify the locale to use for its user interface
elements and for objects in the catalog. These locales can be the same or different. The
user interface elements are available in 10 locales, and the catalog content for certain
applications is available in 28 locales.
You can see the user interface elements of Catalog Manager (dialogs, menus, and so
on) in any of the 10 locales in which it is available. Certain areas of Catalog Manager,

Localizing Oracle Business Intelligence 14-13


Setting the Current Locale in the Oracle BI Server

such as data handling, are not yet translated or localized. Catalog Manager uses the
following process to decide which locale to display:
1. Check for the setting of the "-nl <locale>" parameter when Catalog Manager is
started. You set this parameter as part of the CATMAN_VMARGS variable in the
runcat.cmd or runcat.sh file, as shown in the following examples:
set CATMAN_VMARGS=-nl fr -vmargs -Xmx1024M -Dosgi.clean=true
set CATMAN_VMARGS=-nl fr_CA -vmargs -Xmx1024M -Dosgi.clean=true
2. Check for the default locale for Java, as specified on your computer.
3. Using the default locale of English (specifically, en_US).
When you start Catalog Manager and open a catalog in online mode, you can select
the locale for viewing the contents of the catalog. The locales that are available for
selection depend on the following criteria. Catalog Manager uses this selection for
subsequent online connections.
Whether that locale was selected for Presentation Services during the installation
process.
Whether the contents of the catalog have been translated for a specified locale.
If translated files are not available for that locale, then the contents are displayed in the
default locale of English (specifically, en_US).
Note that:
Session errors (such as login failed or session timed out) are displayed in the
default locale, not necessarily the locale of the user trying to login or whose
session timed out.
Some strings in the Catalog Manager user interface (such as the string Maximize)
are not translated.
For more information on Catalog Manager, see Section 16.3, "About Catalog Manager."

14.4 Setting the Current Locale in the Oracle BI Server


The following sections provide information about setting the locale in Oracle BI
Server:
Section 14.4.1, "Setting Locale Parameters on the Oracle BI Server"
Section 14.4.2, "Understanding How the Error Message Language Is Determined"
Section 14.4.3, "Setting the Language for Components of the Oracle BI Server"
Section 14.4.4, "Modifying the Language of the User Interface for the
Administration Tool"
Section 14.4.5, "Troubleshooting the Current Locale in the Oracle BI Server"
Section 14.4.6, "Ensuring That Text for Oracle BI Server Utilities is Displayed in the
Correct Language"
Section 14.4.7, "Modifying the Metadata Repository When the Underlying Oracle
Database NLS_CHARACTERSET Is Not Unicode"

14.4.1 Setting Locale Parameters on the Oracle BI Server


To support multiple languages, the Oracle BI Server must be configured properly. The
General section of the NQSConfig.INI file contains parameters that are required for

14-14 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Setting the Current Locale in the Oracle BI Server

localization and internationalization. It also contains default parameters that


determine how data is sent from the Oracle BI Server to a client application. See
Appendix A, "Configuration File Settings" for complete information about these
parameters.
The following parameters in the NQSConfig.INI file affect localization:
LOCALE
SORT_ORDER_LOCALE
SORT_TYPE
CASE_SENSITIVE_CHARACTER_COMPARISON
To successfully run Oracle Business Intelligence, ensure that you configure the
appropriate locales on your operating system for the language in which users run the
applications. Some locale- and language-related settings are interrelated and help
determine how the Oracle BI Server sorts data.

14.4.1.1 Setting the Locale on UNIX Systems


The value to use for the C-runtime locale during server startup is specified in the
SORT_ORDER_LOCALE parameter in the NQSConfig.INI file. This parameter is set
normally by the Oracle BI Server. The locale is used for functions such as displaying
dates and currencies and sorting data.
If you must adjust the setting, then in the General section of the NQSConfig.INI file,
set the LOCALE and SORT_ORDER_LOCALE parameters, entering a
platform-independent name as shown in Table 142.
Table 142 shows language mappings from the platform-independent name to the
specific name for each of the supported UNIX platforms. For example, Chinese uses
the setting zh_CN.utf8 on HP-UX or Linux operating systems.
Name strings such as zh_CN.utf8 and fr-FR-UTF-8 are the platform-specific names of
the locale components, which must be installed by a system administrator. The
NQSConfig.INI file uses the platform-independent names, such as Chinese or French
(the names are case-insensitive).

Table 142 LOCALE Settings for UNIX Platforms


Name on
Locale (Platform-Independent Name) Name on Solaris Name on AIX HP-UX/Linux
Arabic ar_SA.UTF-8 AR_AA.UTF-8 ar_SA.utf8
Chinese zh_CN.UTF-8 ZH_CN.UTF-8 zh_CN.utf8
Chinese-traditional zh_TW.UTF-8 ZH_TW.UTF-8 zh_TW.utf8
Croatian hr_HR.UTF-8 HR_HR.UTF-8 hr_HR.utf8
Czech cs_CZ.UTF-8 CS_CZ.UTF-8 cs_CZ.utf8
Danish da_DK.UTF-8 DA_DK.UTF-8 da_DK.utf8
Dutch nl_NL.UTF-8 NL_NL.UTF-8 nl_NL.utf8
English-USA en_US.UTF-8 EN_US.UTF-8 en_US.utf8
Finnish fi_FI.UTF-8 FI_FI.UTF-8 fi_FI.utf8
French fr_FR.UTF-8 FR_FR.UTF-8 fr_FR.utf8
German de_DE.UTF-8 DE_DE.UTF-8 de_DE.utf8

Localizing Oracle Business Intelligence 14-15


Setting the Current Locale in the Oracle BI Server

Table 142 (Cont.) LOCALE Settings for UNIX Platforms


Name on
Locale (Platform-Independent Name) Name on Solaris Name on AIX HP-UX/Linux
Greek el_GR.UTF-8 EL_GR.UTF-8 el_GR.utf8
Hebrew he_IL.UTF-8 HE_IL.UTF-8 iw_IL.utf8
Hungarian hu_HU.UTF-8 HU_HU.UTF-8 hu_HU.utf8
Italian it_IT.UTF-8 IT_IT.UTF-8 it_IT.utf8
Japanese ja_JP.UTF-8 JA_JP.UTF-8 ja_JP.utf8
Korean ko_KR.UTF-8 KO_KR.UTF-8 ko_KR.utf8
Norwegian no_NO.UTF-8 NO_NO.UTF-8 no_NO.utf8
Polish pl_PL.UTF-8 PL_PL.UTF-8 pl_PL.utf8
Portuguese pt_PT.UTF-8 PT_PT.UTF-8 pt_PT.utf8
Portuguese-Brazilian pt_BR.UTF-8 PT_BR.UTF-8 pt_BR.utf8
Romanian ro_RO.UTF-8 RO_RO.UTF-8 ro_RO.utf8
Russian ru_RU.UTF-8 RU_RU.UTF-8 ru_RU.utf8
Slovak sk_SK.UTF-8 SK_SK.UTF-8 sk_SK.utf8
Spanish es_ES.UTF-8 ES_ES.UTF-8 es_ES.utf8
Swedish sv_SE.UTF-8 SV_SE.UTF-8 sv_SE.utf8
Thai th_TH.UTF-8 TH_TH.UTF-8 th_TH.utf8
Turkish tr_TR.UTF-8 TR_TR.UTF-8 tr_TR.utf8

14.4.2 Understanding How the Error Message Language Is Determined


For Oracle BI Presentation Services, the error message language is set based on the
NQ_SESSION.WEBLANGUAGE session variable. Presentation Services provides a
default value for this variable upon installation. The value is updated when a user
selects a language on the Oracle BI EE sign-in page.
For other clients, including third-party clients, the error message language is
determined by the following precedence model:
The error message language is set based on the WEBLANGUAGE session variable.
If the WEBLANGUAGE session variable is not set, then the error message
language is based on the error language that is specified in the ODBC Data Source
Name (DSN) that is used to access the Oracle BI Server.
See Oracle Fusion Middleware Integrator's Guide for Oracle Business Intelligence
Enterprise Edition for information about setting the error message language in the
ODBC DSN.
If an error message language has not been set in the ODBC DSN, then the
language that is specified in the ORACLE_BI_LANG environment variable is used
for error messages.
To change the value of ORACLE_BI_LANG, update the character code for this
variable in NQSConfig.INI. You can view the character codes for supported
languages in the ORACLE_HOME/bi/bifoundation/server/locale directory (for
example, "en" for English, or "pt-BR" for Portuguese/Brazilian).

14-16 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Setting the Current Locale in the Oracle BI Server

If the ORACLE_BI_LANG environment variable is not set, then error messages are
displayed in English.
Note that clients for the Administration Tool and Job Manager do not set the
WEBLANGUAGE session variable. Therefore, these clients follow the precedence
model starting with the ODBC DSN error message setting.

14.4.3 Setting the Language for Components of the Oracle BI Server


To display the correct language for components in the Oracle BI Server, including the
contents of the NQServer.log file, you must set the ORACLE_BI_LANG variable, as
described in the following procedure.
Setting the language for components of the BI Server:
1. Open the NQSConfig.INI file for editing at:
BI_DOMAIN/config/fmwconfig/biconfig/OBIS
2. Insert a line to set the ORACLE_BI_LANG environment variable. The following
example shows the language being set to Japanese:
<variable id="ORACLE_BI_LANG" value="ja"/>
3. Save your changes and close the file.
4. Restart BI system components and the BI Server.
For information, see Chapter 2, "Managing Oracle Business Intelligence Processes".

14.4.4 Modifying the Language of the User Interface for the Administration Tool
The user interface of the Oracle BI Administration Tool inherits the language that is
specified for the operating system. For example, if the Windows operating system is
set to use the French language, then all user interface elements such as menus and
buttons are displayed in French in all Windows-based applications such as Notepad
and the Administration Tool. The locale that you set in the Windows Control Panel
affects items such as currency, dates and times, units displayed, and keyboard layout,
which differ from user interface elements such as menus and buttons.
The recommended approach is to allow the Administration Tool to inherit the
language from the operating system. If you must change the language for the user
interface of the Administration Tool without changing the operating system language,
then you can use the ORACLE_BI_LANG environment variable for this purpose. For
information on setting that variable, see Section 14.4.2, "Understanding How the Error
Message Language Is Determined."
You can also localize the names of subject areas, tables, hierarchies, columns, and their
descriptions in the Presentation layer, as described in Section 14.5, "Localizing
Metadata Names in the Repository."

14.4.5 Troubleshooting the Current Locale in the Oracle BI Server


This section provides the following information about troubleshooting the current
locale in the Oracle BI Server:
Section 14.4.5.1, "Handling the NLS Locale Not Supported Error Message"
Section 14.4.5.2, "Setting the Japanese Locale on AIX Systems"

Localizing Oracle Business Intelligence 14-17


Setting the Current Locale in the Oracle BI Server

14.4.5.1 Handling the NLS Locale Not Supported Error Message


If you do not have the appropriate locale installed, then the Oracle BI Server does not
start, and the NQServer.log file contains the following error:
[47013] NLS locale xxx is not supported by the operating system.
where xxx is the locale that is specified in the NQSConfig.INI file for the SORT_
ORDER_LOCALE parameter. Take the following actions to resolve this error:
UNIX. Install the locale that is indicated in Table 142 for the requested language.
Windows. Add the corresponding language pack using the Regional Settings
dialog.

14.4.5.2 Setting the Japanese Locale on AIX Systems


When using a Japanese localization on an AIX platform, you might discover that the
Oracle BI Server does not start. If you encounter this issue, then use the following
procedure.
To set the Japanese locale on an AIX system:
1. Ensure that the JA_JP.UTF-8 locale is installed. If it is not, then install it.
2. Open the NQSConfig.INI file for editing at:
BI_DOMAIN/config/fmwconfig/biconfig/OBIS
3. In the General section, set the following parameters, being aware that the settings
are case-sensitive:
LOCALE = "Japanese";
SORT_ORDER_LOCALE = "Japanese";
4. Save and close the NQSConfig.INI file.

14.4.6 Ensuring That Text for Oracle BI Server Utilities is Displayed in the Correct
Language
Follow these steps to ensure that usage information and error messages for the Oracle
BI Server utilities are displayed in the correct language:
For Linux environments, set the terminal encoding to UTF-8 to display multibyte
characters. To do this, select the Terminal menu, then select Set Character
encoding, then select utf8.
For native Windows environments, set the font of the console to Lucida Console. If
this option is not displayed in the list, then first change the code page to 65001,
which supports UTF-8, using the command chcp 65001.

14.4.7 Modifying the Metadata Repository When the Underlying Oracle Database NLS_
CHARACTERSET Is Not Unicode
When the NLS_CHARACTERSET in the Oracle Database is set to a non-unicode
derived code page, you must configure an additional metadata repository setting to
make character sorting consistent between the Oracle Database and the Oracle BI
Server.
To modify the metadata repository when the underlying Oracle database NLS_
CHARACTERSET is not unicode:
1. In the Administration Tool, open the metadata repository.

14-18 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Localizing Metadata Names in the Repository

2. Expand the database object in the physical layer.


3. Open the Connection Pool dialog Connection Scripts tab, and add the following
new connection pool script:
alter session set NLS_SORT = unicode_binary
4. Save the repository, and restart the Oracle BI Server.

14.5 Localizing Metadata Names in the Repository


You can use the Externalize Strings utility in the Administration Tool to localize the
names of subject areas, tables, hierarchies, columns, and their descriptions in the
Presentation layer. You can save these text strings to external files with ANSI, Unicode,
and UTF-8 encoding options.
To externalize strings for localization:
1. Open the repository in the Administration Tool.
2. Right-click any Presentation layer object, such as a subject area, presentation table,
or presentation column, and select either Externalize Display Names then
Generate Custom Names, or Externalize Descriptions then Generate Custom
Descriptions to externalize strings. Note that when you select Generate Custom
Names and then run the Externalize Strings utility, the translation key will also
appear in the Externalize Strings dialog.
Selecting one of these right-click externalization options automatically selects the
Custom display name or Custom description options in the Properties dialog for
the selected object and all of its child objects.
For example, if you right-click a subject area and select one of the externalization
options, then the externalization flag is set on all presentation tables, columns,
hierarchies, and levels within that subject area.
3. Select Tools, then select Utilities.
4. Select Externalize Strings and click Execute.
5. In the Externalize Strings dialog, select one or more subject areas in the left pane.
In the right pane, the translated values and the original strings (names and
descriptions) are displayed. These are placed in session variables for use by
Presentation Services.
Only those objects with the externalization flag set in the Presentation layer are
displayed in the right pane.
6. Click Save.
7. In the Save As dialog, do one of the following:
If you selected a single subject area, then select a type of file and an encoding
value and click Save.
If you selected multiple subject areas and want each one externalized in its
own XML file, then select a directory name and press SHIFT while clicking
Save. Each subject area is saved to an XML file with Unicode encryption.
8. In the Externalized Strings dialog, click Close.
9. (Optional) To disable externalization, right-click a Presentation layer object and
select Externalize Display Names, then Disable Externalization, or Externalize
Descriptions then Disable Externalization.

Localizing Oracle Business Intelligence 14-19


Localizing Metadata Names in the Repository

Selecting one of these options automatically deselects the Custom display name or
Custom description options in the Properties dialog for the selected object and all
of its child objects.
When you have created the string files using the Externalize Strings utility, you can
use the files to translate the strings for the metadata objects, as described in the
following procedure.
To translate strings for metadata from the exported string files:
1. Open each string file and examine the columns:
The first column contains the actual repository object names, which have a
prefix of their type.
The second column contains the session variables that correspond to the name
of each object or description, with a default prefix of CN_ for custom names
and CD_ for custom descriptions.
The third column contains the translation keys that correspond to the name of
each object.
2. Add a fourth column called Language. In this column, specify the code for the
language in which the name was translated, such as de.
3. Load each string file into a database table.
4. In the Administration Tool, import the table into the physical layer.
5. Load the translated strings using row-wise initialization blocks. Ensure that you
set the target of the initialization block to Row-wise initialization and that the
execution precedence is set correctly.
For example, you could do the following:
a. Create a session initialization block that has the data source from a database,
using a SQL statement such as the following one:
SELECT 'VALUEOF(NQ_SESSION.WEBLANGUAGE)' FROM DUAL

b. In the Session Variable Initialization Block dialog for SET Language, specify
the LOCALE session variable for the Variable Target.
This specification ensures that whenever a user signs in, the WEBLANGUAGE
session variable is set. Then this variable sets the LOCALE variable using the
initialization block.
c. Create another session initialization block that creates a set of session variables
using a database-specific SQL statement such as the following one in the
Session Variable Initialization Block Data Source dialog:
select SESSION_VARIABLE, TRANSLATION from external where LANGUAGE =
'VALUEOF(NQ_SESSION.LOCALE)'

This block creates all the variables whose language matches the language that
the user specified during sign-in.
d. In the Session Variable Initialization Block Variable Target dialog, set the target
of the initialization block to Row-wise initialization.
e. In the Execution Precedence area of the Session Variable Initialization Block
dialog, specify the previously created initialization block, so that the first block
that you created earlier is executed first.
6. Save your changes.

14-20 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Supporting Multilingual Data

Tips: For information on the language for the Administration Tool,


see Section 14.4.4, "Modifying the Language of the User Interface for
the Administration Tool."
If you have an Oracle Application Development Framework data
source, then you can propagate labels and tooltips from that data
source, instead of using the Externalize Strings utility. See Oracle
Fusion Middleware Metadata Repository Builder's Guide for Oracle
Business Intelligence Enterprise Edition for information.

14.6 Supporting Multilingual Data


This section describes how you can configure the Oracle BI Server to display field
information in multiple languages, and contains the following topics:
Section 14.6.1, "What is Multilingual Data Support?"
Section 14.6.2, "What is Lookup?"
Section 14.6.3, "What is Double Column Support?"
Section 14.6.4, "Designing Translation Lookup Tables in a Multilingual Schema"
Section 14.6.5, "Creating Logical Lookup Tables and Logical Lookup Columns"
Section 14.6.6, "Creating Physical Lookup Tables and Physical Lookup Columns"
Section 14.6.7, "Supporting Multilingual Data in Essbase Through Alias Tables"
Section 14.6.8, "Enabling Lexicographical Sorting"
For information about using the Administration Tool, see Oracle Fusion Middleware
Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition.

14.6.1 What is Multilingual Data Support?


Multilingual data support is the ability to display data from database schemas in
multiple languages. Oracle BI Server supports multilingual schemas by simplifying
the administration and improving query performance for translations. Multilingual
schemas typically store translated fields in separate tables called lookup tables.
Lookup tables contain translations for descriptor columns in several languages, while
the base tables contain the data in the base language. Descriptor columns provide a
textual description for a key column where there is a logical one-to-one relationship
between the descriptor column and the key column. An example of a descriptor
column might be Product_Name, which provides textual descriptions for a Product_
Key column.

14.6.2 What is Lookup?


Lookup is when a query joins the base table and lookup table to obtain the translated
values for each row in the base table.
Lookup tables might be dense and sparse in nature. A dense lookup table contains
translations in all languages for every record in the base table. A sparse lookup table
contains translations for only for some records in the base tables. Sometimes it is also
possible that lookup tables are both dense and sparse. For example, a lookup table
might contain complete translation for the Product Description field but only partial
translation for the Product Category field. Dense and Sparse are types of lookup
operation rather than being a table property. You configure lookup tables using the
Administration Tool.

Localizing Oracle Business Intelligence 14-21


Supporting Multilingual Data

14.6.3 What is Double Column Support?


Double column support is the ability to associate two columns (a descriptor ID column
and a descriptor column) in the logical layer, and can help you to define language
independent filters. When the user creates a filter based on a descriptor column, the
query tool displays a list of values to the user that are selected from the descriptor
column.
This descriptor column technique is also useful when dealing with queries that
involve LOB data types such as CLOBs and BLOBs and aggregate functions such as
COUNT or SUM. Some data sources do not allow LOB columns to be used in the GROUP BY
clause. So, instead of adding the LOB column to the GROUP BY, it is necessary to group
by some other column that has a one-to-one relationship with the LOB column and
then in join the LOB column after the aggregates have been computed.

14.6.4 Designing Translation Lookup Tables in a Multilingual Schema


There are two common techniques of designing translation lookup tables in a
multilingual schema as follows:
Section 14.6.4.1, "A Lookup Table for Each Base Table"
Section 14.6.4.2, "A Lookup Table for Each Translated Field"

14.6.4.1 A Lookup Table for Each Base Table


There is often a separate lookup table for each base table. The lookup table contains a
foreign key reference to records in the base table, and contains the values for each
translated field in a separate column. Assuming a completely dense lookup table, the
number of rows in the lookup table for a particular language equals the number of
rows in the base table.
The example in Figure 145 shows each record in the lookup table matching only one
row in the base table.

Figure 145 Lookup Table For Each Base Table

14.6.4.2 A Lookup Table for Each Translated Field


The alternative approach to having one lookup table for each base table involves a
separate lookup table for each translated field, as shown in Figure 146. Getting the
translated value of each field requires a separate join to a lookup table. In practice
there is often just one physical table that contains translations for multiple fields.
When a single table contains translations for multiple fields, you must place a filter on
the lookup table to restrict the data to only those values that are relevant to a
particular column in the base table.

14-22 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Supporting Multilingual Data

Figure 146 Lookup Table For Each Translated Field

14.6.5 Creating Logical Lookup Tables and Logical Lookup Columns


This section describes creating logical lookup tables and lookup columns and contains
the following topics:
Section 14.6.5.1, "Creating Logical Lookup Tables"
Section 14.6.5.2, "Designating a Logical Table as a Lookup Table"
Section 14.6.5.3, "About the LOOKUP Function Syntax"
Section 14.6.5.4, "Creating Logical Lookup Columns"

14.6.5.1 Creating Logical Lookup Tables


You create a logical lookup table object in the business model to define the necessary
metadata for a translation lookup table. A lookup table is a logical table with a
property that designates it as a lookup table, as described in Section 14.6.5.2,
"Designating a Logical Table as a Lookup Table." Figure 147 provides an example of a
lookup table.

Figure 147 Example of a Lookup Table

Each of the lookup table's primary keys are considered together as a Lookup Key
and perform the lookup. The lookup can be performed only when the values for
all lookup key columns are provided. For example, in Figure 147, the combined
Product_Code and Language_Key form the primary key of this lookup table.
A lookup key is different from a logical table key because lookup key columns are
order sensitive. For example, Product_Code and Language_Key are considered a
different lookup key to Language_Key and Product_Code. You can specify the

Localizing Oracle Business Intelligence 14-23


Supporting Multilingual Data

order of lookup key columns in the Administration Tool. All columns of the
lookup key must be joined in the lookup function.
A lookup table has only one lookup key.
A lookup table has at least one value column. In Figure 147, the value column is
Description, and it contains the translated value for the product description.
There must be a functional dependency from a lookup key to each value column.
In other words, the lookup key can identify the value column. The lookup key and
value column should both belong to the same physical table.
A lookup table is standalone without joining to any other logical tables.
Consistency checking rules are relaxed for lookup tables, such that if a table is
designated as a lookup table, it need not be joined with any other table in the
subject area (logical tables would normally be joined to at least one table in the
subject area).
The aggregation results when using lookup columns should match the results
from the base column. For example, the following code
SELECT product.productname_trans, sales.revenue FROM snowflakesales;

should return the same results as


SELECT product.productname, sales.revenue FROM snowflakesales;

If the lookup table productname_trans in this example uses the lookup key
ProductID and LANGUAGE, then both queries return the same aggregation
results.
If the lookup key contains a column with a different aggregation level to
productname, then the query grain changes and this affects the aggregation.

14.6.5.2 Designating a Logical Table as a Lookup Table


A logical table must be designated as a lookup table (using the Administration Tool)
before you can use it as a lookup table. To designate a logical table as a lookup table,
you must first import the lookup table into the physical layer and drop it into the
Business Model and Mapping layer using the Administration Tool. Then, for each
logical lookup table, you must select the Lookup table option in the Logical Table
dialog.
The order in which the columns are specified in the lookup table primary key
determines the order of the corresponding arguments in the LOOKUP function.
For example, if the lookup table primary key consists of the RegionKey, CityKey, and
LanguageKey columns, then the matching arguments in the LOOKUP function must be
specified in the same order. You use the Administration Tool to change the order of
primary key columns.

14.6.5.3 About the LOOKUP Function Syntax


A LOOKUP function is typically used in the Business Model and Mapping layer, as an
expression in a translated logical table column.
The syntax of the LOOKUP function is as follows:
Lookup ::= LookUp([DENSE] value_column, expression_list ) | LookUp(SPARSE value_
column, base_column, expression_list )

expression_list ::= expr {, expression_list }

14-24 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Supporting Multilingual Data

expr ::= logical_column | session_variable | literal

For example:
LOOKUP( SPARSE SnowflakeSales.ProductName_TRANS.ProductName,
SnowflakeSales.Product.ProductName, SnowflakeSales.Product.ProductID, VALUEOF(NQ_
SESSION."LANGUAGE"))

LOOKUP( DENSE SnowflakeSales.ProductName_TRANS.ProductName,


SnowflakeSales.Product.ProductID, VALUEOF(NQ_SESSION."LANGUAGE"))

Note the following:


A LOOKUP function is either dense or sparse, and is specified using the keyword
DENSE or SPARSE. The default behavior is dense lookup, if neither DENSE or SPARSE
is specified. For DENSE lookup, the translation table is joined to the base table
through an inner join, while for SPARSE lookup, a left outer join is performed.
The first parameter (the parameter after the DENSE or SPARSE keyword) must be a
valid value column from a valid lookup table that is defined in the logical layer.
If the SPARSE keyword is given, then the second parameter must be a column that
provides the base value of the value_column. For DENSE lookup, this base column
is not required.
The number of expressions in the expression_list must be equal to the number of
the lookup key columns that are defined in the lookup table, which is defined by
the value_column. The expression that is specified in the expression list must also
match the lookup key columns one by one in order.
For example:
The lookup key for lookup table ProductName_TRANS is both Product_code
and Language_Key
The expressions in expression_list are SnowflakeSales.Product.ProductID and
VALUEOF(NQ_SESSION."LANGUAGE")
The meaning of the lookup is:
return the translated value of ProductName from the translation table with the
condition of Product_code = SnowflakeSales.Product.ProductID and
Language_Key = VALUEOF(NQ_SESSION."LANGUAGE")

14.6.5.4 Creating Logical Lookup Columns


You use the Expression Builder in the Administration Tool to create a logical column
that includes the lookup function. The value of the logical column depends on the
language that is associated with the current user.
You create a new logical column using a derived column expression in the Column
Source tab, for example to get the translated product name:
INDEXCOL( VALUEOF(NQ_SESSION."LAN_INT"), "Translated Lookup Tables"."Product".
"ProductName", LOOKUP( DENSE "Translated Lookup Tables"."Product Translations".
"ProductName", "Translated Lookup Tables"."Product"."ProductID",
VALUEOF(NQ_SESSION."WEBLANGUAGE")))

LAN_INT is a session variable that is populated by the session initialization block MLS
and represents either the base language or other languages:
0 for base language (for example, en - English)

Localizing Oracle Business Intelligence 14-25


Supporting Multilingual Data

1 for other language codes (for example, fr - French, or cn - Chinese)


WEBLANGUAGE is a session variable that is initialized automatically, based on the
language selected when a user logs in.
The INDEXCOL function helps to select the appropriate column. In the preceding
example, the expression returns the value of the base column (ProductName) only if
the user language is the base language (that is, when the value of session variable LAN_
INT is 0). If the user language is not the base language (when the value of the session
variable LAN_INT is 1), then the expression returns the value from the lookup table of
the language that is passed in the WEBLANGUAGE session variable.
When you use the DENSE function (shown in the previous example), if there is no value
for a column in the translated language, then the lookup function displays a blank
entry.
When you use the SPARSE function (shown in the following example), and there is no
value for a column in the translated language, then the lookup function displays a
corresponding value in the base language.
INDEXCOL( VALUEOF(NQ_SESSION."LAN_INT"), "Translated Lookup Tables"."Product".
"ProductName", LOOKUP( SPARSE "Translated Lookup Tables"."Product Translations".
"ProductName", "Translated Lookup Tables"."Product"."ProductName", "Translated
Lookup Tables"."Product"."ProductID", VALUEOF(NQ_SESSION."WEBLANGUAGE")))

14.6.5.4.1 Tips for Using Derived Logical Columns When working with logical lookup
columns, keep the following tips in mind:
You cannot use a derived logical column that is the result of a LOOKUP function as
part of a primary logical level key. This limitation exists because the LOOKUP
operation is applied after aggregates are computed, but level key columns must be
available before the aggregates are computed because they define the granularity
at which the aggregates are calculated.
You can use a derived logical column that is the result of a LOOKUP function as a
secondary logical level key.
For a derived logical column that has lookup functions in its derived expression:
The logical columns used in the lookup function should not have their
associated levels below the level of the derived logical column itself.
Configuring a descriptor ID column is the recommended approach.

14.6.5.4.2 Handling Non-ISO Type Language Codes If the data has non-ISO type language
codes in the tables, then there should be a table that maps ISO language codes to
non-ISO language codes. You can use the preexisting WEBLANGUAGE variable that sets
the ISO language code when a user logs in. You define a separate LANGUAGE variable
whose initialization block runs a query against a mapping table to fetch the non-ISO
language code filtered by the value from the WEBLANGUAGE variable. Table 143
provides a mapping table for non-ISO language codes. LANGUAGE is a non-ISO
language code.

Table 143 Mapping Table for Non-ISO Language Codes


WEBLANGUAGE LANGUAGE LAN_INT
en ENG 0
cn CHI 1
fr FRA 1

14-26 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Supporting Multilingual Data

14.6.6 Creating Physical Lookup Tables and Physical Lookup Columns


You can create physical lookup table objects in the business model to define the
necessary metadata for translation lookup tables. Physical lookup tables are similar to
logical lookup tables in both semantics and usage. Physical lookup tables address the
following scenarios that logical lookup tables cannot handle:
The lookup table source is fragmented. In this case, use multiple physical lookup
tables to hold the values. For example, translation values for fragmented product
name data can be distributed in two physical lookup tables called productname_
trans_AtoM and productname_trans_NtoZ.
Different levels of translation tables are available. For example, translations are
available in both an Essbase data source and a relational data source. It is
preferable to use the same source as the base query.
Unlike logical lookup tables, which you designate by selecting an option in the Logical
Table dialog, you configure physical lookup tables by constructing lookup functions in
the logical table source mapping.
For example, suppose that you have the following physical tables:
A base table called Categories, with columns such as categoryid and
categoryname.
A translation table called Categories_Trans, with columns such as categoryid,
language_key, and categoryname. The translated value of categoryname is
determined through a combination of the categoryid and language_key columns.
Suppose that you have a logical table called Categories. In that table, you add a new
logical column called categoryname_p, which is a translation column that depends on
the current language. The column is not derived from any other logical column (unlike
logical lookup columns).
The following procedure explains how to configure a physical lookup translation
column using the previous example.
To configure a translation column that is derived from a physical lookup table:
1. Open the repository in the Administration Tool.
2. In the Business Model and Mapping layer, create a new logical column by
right-clicking the appropriate logical table (for example, Categories) and selecting
New Object, then Logical Column.
3. Provide a name for the logical column (for example, categoryname_p).
4. Select the Column Source tab.
5. In the Logical Table Source box under Derived from physical mappings,
double-click the logical table source object that contains the base table column. The
Column Mapping tab of the Logical Table Source dialog is displayed.
6. Ensure that Show unmapped columns is selected.
7. In the Expression column for the new logical column (for example, categoryname_
p), enter an expression such as the following:
INDEXCOL(VALUEOF(NQ_SESSION."LAN_INT"),
"DB_Name"."My_Category"."My_Schema"."Categories"."CategoryName", LOOKUP(SPARSE
"DB_Name"."My_Category"."My_Schema"."CATEGORIES_TRANS"."CATEGORYNAME",
"DB_Name"."My_Category"."My_Schema"."Categories"."CategoryName",
"DB_Name"."My_Category"."My_Schema"."Categories"."CategoryID",
VALUEOF(NQ_SESSION."LANGUAGE")))

Localizing Oracle Business Intelligence 14-27


Supporting Multilingual Data

You can also use Expression Builder to create the expression.


8. Click OK in the Logical Table Source dialog.
9. Click OK in the Logical Column dialog.
10. Save your changes.

The Categories_trans physical translation table does not need to be incorporated into
the logical table source. The INDEXCOL function checks that if the LAN_INT session
variable is 0, then the categoryname column is fetched from the base table. Note the
following about the LOOKUP function:
The physical LOOKUP function works the same as a logical LOOKUP function. The
only difference is that all the references to logical tables and columns are replaced
by physical tables and columns.
The first column of the LOOKUP function is a value column, which is a translation
value column from a translation table. The second column is the base value
column, if a sparse lookup exists. The remaining columns are columns or values to
be joined to the physical translation table, which is the table that is implied by the
value column of the LOOKUP function.
Because you cannot use a dialog to configure a physical lookup table, you must ensure
that the order of the join columns and values is compatible with the column sequence
that is displayed in the Physical Table dialog for the physical translation table. For
example, on the Keys tab of the Physical Table dialog for the Categories_trans table,
the primary key is composed of the CategoryID and Language_Key columns.
The columns that are specified in the LOOKUP function correspond to these columns:
The following line:
"DB_Name"."My_Category"."My_Schema"."Categories"."CategoryID"

corresponds to the Categories_trans.CategoryID column.


The following line:
valueof(NQ_SESSION."LANGUAGE")

corresponds to the Categories_trans.Language_key column.


See Section 14.6.5, "Creating Logical Lookup Tables and Logical Lookup Columns" for
information about lookup concepts like the LAN_INT and LANGUAGE session variables
and full syntax information for the LOOKUP function.

14.6.7 Supporting Multilingual Data in Essbase Through Alias Tables


Often, members in Essbase cubes have separate aliases for each user language to
enable users to view member names in their own language. Typically, you define a
session variable to dynamically select the appropriate alias upon user login. See Oracle
Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence
Enterprise Edition for information about Essbase alias tables and how to use them with
session variables.

14.6.8 Enabling Lexicographical Sorting


Lexicographical sorting is the ability to sort data in alphabetical order. Most data
sources support lexicographical sorting. However, if you notice that lexicographical
sorting is not working properly for a particular data source, then you can configure the
Oracle BI Server to perform the sort rather than the back-end data source. To perform

14-28 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Supporting Multilingual Data

this configuration, ensure that ORDERBY_SUPPORTED is not selected in the Features


tab of the Database dialog in the Administration Tool. See Oracle Fusion Middleware
Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition for
information about specifying database features.
Note that disabling ORDERBY_SUPPORTED in the data source can have a very large
performance impact, because consequently, many joins are not pushed down to the
data source. In many cases, the performance impact is significant enough that
ORDERBY_SUPPORTED can still be enabled in the data source, regardless of the
impact on the lexicographical sorting functionality.

Localizing Oracle Business Intelligence 14-29


Supporting Multilingual Data

14-30 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
15
Configuring Currency Options
15

This chapter describes how to configure currency options in Oracle Business


[16]

Intelligence. When content designers create analyses, they often include data that
shows currency, such as American dollars. As the administrator, you can perform
various tasks that affect currency options that are available to users.
This chapter includes the following sections:
Changing the Default Currency for Analyses
Defining User-Preferred Currency Options

15.1 Changing the Default Currency for Analyses


You can change the default currency that is displayed, for example, from French
Francs to Euros. For information about using formatting functions in Answers, see
Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.
To set the default currency:
1. Open the currencies.xml file in the directory
ORACLE_HOME/bi/bifoundation/web/display.
2. Search for the currency to make the default, for example, USD, CAD, PEN, or
MAD.
3. Copy the entire currency element.
For example, copy the currency tag for the Euro:
- <Currency tag="int:euro-l" type="international" symbol="_"
displayMessage="kmsgCurrencyEuroLeft" digits="2" format="$ #">
<negative tag="minus" format="-$ #" />
</Currency>

4. Search for the text string int:wrhs, located near the top of the file.
5. Select the entire element and replace it by pasting the copied element over it.
6. Replace the tag attribute so it reads int:wrhs.
For example, replace tag="int:euro-l" with tag="int:wrhs".
7. Restart the service for Oracle BI Presentation Services.

Configuring Currency Options 15-1


Defining User-Preferred Currency Options

Caution: The currencies.xml file is overwritten when applying an


upgrade, a patchset, a bundle patch, or a one-off patch. If you have
made changes to this file, reenter your changes in the new
currencies.xml.

To specify the currency for a column in a customized subject area:


1. In Answers, modify the analysis that uses the subject area.
2. In the Analysis editor: Criteria tab, click the Options button for the currency
column and select Column Properties to display the Column Properties dialog.
3. Click the Data Format tab and select the Override Default Data Format box.
4. In the Treat Numbers As box, select Currency.
5. In the Currency Symbol list, select User's Preferred Currency.
6. Complete the other options on the tab as appropriate.
7. If desired, save this setting as a systemwide default.
8. Click OK when you have finished, and repeat the preceding steps for any other
columns to change.
Considerations for defining user-preferred currency:
To create a default for all users, set the CURRENCYTAG element using an INIT
BLOCK.
If you configure a user-preferred currency, set the PREFERRED_CURRENCY
element using an INIT BLOCK.
For more information about defining user-preferred currency options, see
Section 15.2, "Defining User-Preferred Currency Options".
For more information about INIT BLOCKs, see "Working with Initialization
Blocks" in Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle
Business Intelligence Enterprise Edition.

15.2 Defining User-Preferred Currency Options


Users can select the currency in which they prefer to view currency columns in
analyses and dashboards in two ways:
In the Currency box on the My Account dialog: Preferences tab
In currency prompts

15-2 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Defining User-Preferred Currency Options

Figure 151 Example of the Currency Box on the My Account Dialog: Preferences Tab

For information about setting the currency preference on the My Account dialog:
Preferences tab or about currency prompts, see Oracle Fusion Middleware User's Guide
for Oracle Business Intelligence Enterprise Edition.
You define the currency options that are to be displayed in the Currency box and in a
currency prompt in the userpref_currencies.xml file. (These currency options must be
for currencies to which your installation can convert columns.) Defining the currency
options also controls whether the Currency box is available on the My Account dialog:
Preferences tab and whether the Currency Prompt option is available on the Definition
pane of the Prompt editor.
When you define these currency options, you can use one of two types of mappings:
Static Produces a static list of currency options that all users see.
Dynamic Produces a list of currency options that changes dynamically based
on a logical SQL statement that you specify. This is useful, for example, to
dynamically change the currency options so that each user sees a list specific to his
or her account. Each user sees a subset of the total options available. For example,
one group of users might want to select from only Global Currency 1 or Global
Currency 2 while another group might want to select from different options.

Note: For the user-preferred currency options to take effect, the


following configuration also must be done in the Oracle Business
Intelligence repository:
Creation of the PREFERRED_CURRENCY session variable.
Conversion setup of logical currency columns in the Business
Model and Mapping layer
Creation of the userCurrencyPreference table using the currency
information from your installation that enables you to
dynamically change the currency options based on a logical SQL
statement that you specify (required only if you use a dynamic
mapping)
For information, see "Configuring Logical Columns for Multicurrency
Support" in Oracle Fusion Middleware Metadata Repository Builder's
Guide for Oracle Business Intelligence Enterprise Edition.

Configuring Currency Options 15-3


Defining User-Preferred Currency Options

You can set the contents of the user's preferred currency by using the PREFERRED_
CURRENCY session variable. You define the UserCurrencyPreferences element in any
one of the following files:
instanceconfig.xml file, or in userpref_currencies.xml files located in:
BI_DOMAIN/config/fmwconfig/biconfig/OBIPS
yourfilename, where the instanceconfig.xml file contains an entry pointing to your
file. For example,
<UserprefCurrenciesConfigFile>yourpath</UserprefCurrenciesConfigFile>

where, yourpath is the location of the file.

15.2.1 Defining User-Preferred Currency Options Using a Static Mapping


You can use a mapping to define a static list of options that all users see for selecting
currency.
To define the user-preferred currency options using a static mapping:
1. Use a text editor to open the userpref_currencies.xml file located in the following
directory:
BI_DOMAIN/config/fmwconfig/biconfig/OBIPS
2. Add a UserCurrencyPreferences element as follows:
<UserCurrencyPreferences currencyTagMappingType="static">

</UserCurrencyPreferences>

3. For each currency option to be displayed in the Currency box or in currency


prompts, add a UserCurrencyPreference element between the
<UserCurrencyPreferences> tags using this format:
<UserCurrencyPreference sessionVarValue="sessionVarValuevalue"
displayMessage="displayMessagevalue" displayText="displayTextvalue"
currencyTag="currencyTagvalue"/>

In this format:
sessionVarValue="sessionVarValue " sets the session variable PREFERRED_
CURRENCY. For its value, specify a string that uniquely identifies the
currency, for example, gc1.
(optional) displayMessage="displayMessagevalue" sets the presentation variable
currency.userPreference to a localized value. To specify a localized value, you
first must create the localized message for the currency in the
usercurrencymessages.xml file. For information, see Section 14.2.1.2,
"Localizing Messages for Users' Preferred Currency." Then, for the value of
displayMessage, specify the WebMessage name that is identified in the
usercurrencymessages.xml file for the currency. For example, if you created
this English language entry in the usercurrencymessages.xml file:
<WebMessage name="kmsgMyCurrency1"><TEXT>My Currency 1</TEXT></WebMessage>

Then you would specify kmsgMyCurrency1 as the value of displayMessage.


(optional) displayText="displayTextvalue" sets the presentation variable
currency.userPreference to a value that is not localized. For its value, specify a
string that identifies the currency, such as Global Currency 2.

15-4 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Defining User-Preferred Currency Options

For more information about the currency.userPreference variable, see Oracle


Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition
currencyTag="currencyTagvalue" identifies the Currency Tag in the
currencies.xml file whose displayMessage value is to be used to populate the
Currency box on the My Account dialog: Preferences tab and currency
prompts. (The currencies.xml file, which is located in ORACLE_
HOME/bi/bifoundation/web/display, provides currency formats.)

Note: The value of the currency.userPreference variable is obtained


from the displayMessage and displayText attributes of the
UserCurrencyPreference element using the following order of
precedence:
1. displayText
2. displayMessage
If no values exist for displayText and displayMessage, then the value
of the displayMessage attribute for the corresponding currency tag in
the currencies.xml file is used.

4. Save and close the userpref_currencies.xml file.


5. Restart Oracle Business Intelligence.
For information, see Section 2.1, "About Managing Oracle Business Intelligence
Processes."

15.2.2 Example: Static Mapping to Define User-Preferred Currency Options


The following example shows a userpref_currencies.xml file that uses a static mapping
to define user-preferred currency options:
<UserCurrencyPreferences currencyTagMappingType="static">
<UserCurrencyPreference sessionVarValue="gc1" displayText="Global Currency 1"
currencyTag="int:USD" />
<UserCurrencyPreference sessionVarValue="gc2" displayText="Global Currency 2"
currencyTag="int:euro-l" />
<UserCurrencyPreference sessionVarValue="gc3" displayText="Global Currency 3"
currencyTag="loc:ja-JP" />
<UserCurrencyPreference sessionVarValue="orgc" displayText="Org Currency"
currencyTag="loc:en-BZ" />
</UserCurrencyPreferences>

Figure 152 shows how these values from the userpref_currencies.xml file are
displayed in a drop-down list of currency options for a prompt on a dashboard page.
The drop-down list is similar to what is displayed for the Currency box on the My
Account dialog: Preferences tab.

Configuring Currency Options 15-5


Defining User-Preferred Currency Options

Figure 152 Static Currency Options in a Prompt

15.2.3 Defining User-Preferred Currency Options Using a Dynamic Mapping


You can use a mapping to define a dynamic list of options that users see for selecting
currency. The list changes dynamically based on a logical SQL statement that you
specify. This is useful, for example, to dynamically change the currency options based
on the user.
To define user-preferred currency options using a dynamic mapping:
1. Use a text editor to open the userpref_currencies.xml file that is located in the
following directory:
BI_DOMAIN/config/fmwconfig/biconfig/OBIPS
2. Add a UserCurrencyPreferences element as follows:
<UserCurrencyPreferences currencyTagMappingType="dynamic">

</UserCurrencyPreferences>

3. Add a UserPrefCurrencyLogicalSQL element between the


<UserCurrencyPreferences> tags using this format:
<UserPrefCurrencyLogicalSQL>
SELECT column1, column2, column3 FROM userCurrencyPreference
</UserPrefCurrencyLogicalSQL>

In this format:
column1 contains the values that are used to set the session variable
PREFERRED_CURRENCY. Each value in this column is a string that uniquely
identifies the currency, for example, gc1.
column2 contains the currency tags in the currencies.xml file whose
displayMessage values are to be used to populate the Currency box and
currency prompts, for example, int:euro-1. (The currencies.xml file, which is
located in ORACLE_HOME/bi/bifoundation/web/display, provides currency
formats.)
(optional) column3 contains the values used to set the presentation variable
currency.userPreference. Each value in this column is a string that identifies
the currency, such as Global Currency 2.

Note: If you omit column3, then the values for the displayMessage
attributes for the corresponding currency tags in the currencies.xml
file are used.

For more information about the currency.userPreference variable, see Oracle


Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition

15-6 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Defining User-Preferred Currency Options

4. Save and close the userpref_currencies.xml file.


5. Restart Oracle Business Intelligence.
For information, see Section 2.1, "About Managing Oracle Business Intelligence
Processes."

15.2.4 Example: Dynamic Mapping to Define User-Preferred Currency Options


The following example shows a userpref_currencies.xml file that uses a dynamic
mapping to define user-preferred currency options:
<UserCurrencyPreferences currencyTagMappingType="dynamic">
UserPrefCurrencyLogicalSQL>
<!-- In this SELECT statement, column1 contains the values to set the PREFERRED_
CURRENCY variable, column2 contains the currency tag values, and column3 contains
the values to set the currency.userPreference variable. -->
SELECT markets.userpreferences, markets.currencyTag, markets.userpreferencename
FROM userCurrencyPreference
</UserPrefCurrencyLogicalSQL>
</UserCurrencyPreferences>

Table 151 shows sample results from the logical SQL statement.

Table 151 Sample Logical SQL Results


"Markets"."UserPreference" "Markets"."CurrencyTag" "Markets"."UserPreferenceName"
varchar varchar varchar
orgc1 loc:en-BZ Org currency
gc2 int:euro-1 Global currency 2
lc1 int:DEM Ledger currency
gc1 int:USD Global Currency 1

Figure 153 shows how the values that are generated dynamically from the SQL
statement in the userpref_currencies.xml file are displayed in a drop-down list of
currency options for the Currency box on the Preferences tab of the My Account
dialog. The drop-down list is similar to what is displayed for a prompt on a dashboard
page.

Configuring Currency Options 15-7


Defining User-Preferred Currency Options

Figure 153 Dynamic Currency Options in the My Account Dialog

15-8 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
16
Configuring and Managing the Oracle BI
16

Presentation Catalog

This chapter describes how to configure and manage the Oracle BI Presentation
[17]

Catalog and provides information about basic maintenance procedures and


configuring for full-text searching.
This chapter includes the following sections:
About the Oracle BI Presentation Catalog
Maintaining the Oracle BI Presentation Catalog
About Catalog Manager
Starting Catalog Manager and Opening Catalogs
Using the Catalog Manager Workspace
Working with Objects in Catalog Manager
Viewing and Editing Catalog Objects in XML
Searching for and Replacing Catalog Text Using Catalog Manager
Creating Reports to Display Catalog Data Using Catalog Manager
Archiving and Unarchiving Using Catalog Manager

16.1 About the Oracle BI Presentation Catalog


The Oracle BI Presentation Catalog stores the content that users create in a directory
structure of individual files. This content includes folders, shortcuts, Oracle BI EE
objects (such as analyses, filters, prompts, and dashboards), and Oracle BI Publisher
objects (such as reports and templates).
This section contains the following topics:
Section 16.1.1, "Objects in the Catalog"
Section 16.1.2, "File System Guidelines for Catalogs"

16.1.1 Objects in the Catalog


Figure 161 shows sample objects in the catalog, as seen in Presentation Services.

Configuring and Managing the Oracle BI Presentation Catalog 16-1


About the Oracle BI Presentation Catalog

Figure 161 Sample Objects in the Catalog in Presentation Services

16.1.1.1 Guidelines for Object Names


Each object in the catalog is stored in its own file. For example, an analysis called
Analysis 1 is stored in a file named Analysis1. The object name that is visible to users,
such as Analysis 1, is referred to as the logical object name.
The following list provides guidelines for object names:
No restrictions exist on which characters are allowed in the logical name of an
object in the catalog, provided that the characters are valid Unicode characters.
The following are valid logical names:
Hello World
Profit / Loss
% Sales * $ Cost ~~ $ "Expense"?

The length of the logical object name must not exceed 256 Unicode characters.
For more information on Unicode, see Section 16.1.2, "File System Guidelines for
Catalogs."
The length of the logical path name for an object must not exceed 16000 Unicode
characters.
The number of directory segments in a logical path name for an object must be not
exceed 255 segments.
For example, a directory with a name such as
/n1/n2/n3/n4/./n253/n254/n255 is acceptable, while a name such as
/n1/n2/n3/n4/./n254/n255/n256 is unacceptable.
When you pass the path name of an object using SOAP, you must escape the
following characters:
Forward slash (/)
Backward slash (\)
Tilde (~)
Asterisk (*)
Question mark (?)

The following logical path names are all valid:


/shared/test/Hello World
/shared/test/Profit \/ Loss
/shared/test/% Sales \* $ Cost \~\~ $ "Expense"\?

16-2 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
About the Oracle BI Presentation Catalog

Use care when building a catalog path. It is very common to see code that assumes
the forward slash (/) is always a path separator. Always verify your path code
with an object name such as "Profit / Loss".
When you pass a catalog search filter using SOAP, you must escape the following
characters:
Forward slash (/)
Backward slash (\)
Tilde (~)
Asterisk (*)
Question mark (?)
Caret (^)
Dollar sign (?)

The following search filters are all valid:


Hello World
Profit \/ Loss
% Sales \* \$ Cost \~\~ \$ "Expense"\?

16.1.1.2 Attribute Files for Objects


Each object has a corresponding attribute file. For example, the analysis called
Analysis1 would have a corresponding attribute file named Analysis1.atr. The
attribute file contains the object's full name, access control list (ACL), description, and
so on. To access an object in the catalog, users must have appropriate ACL entries for
that object. All objects in the catalog use ACL entries.

16.1.1.3 Lock Files for Objects


To guarantee that only one user can write to a file at one time, a lock file is created
when an object is being written to. On rare occasions (for example, after a power
outage), temporary lock files in the catalog might not be removed completely. If
Presentation Services reports of such a lock file, then you must delete it manually.

16.1.2 File System Guidelines for Catalogs


This section describes the following guidelines for working with objects in catalogs in
file systems:
Section 16.1.2.1, "Handling Users of the Catalog"
Section 16.1.2.2, "Handling Heterogeneous Nodes"
Section 16.1.2.3, "Handling Catalog Files on Various Platforms"
Section 16.1.2.4, "Known Issues with Catalog Files"

16.1.2.1 Handling Users of the Catalog


The catalog is designed to scale to thousands of concurrent users. To achieve this
scaling, the catalog adheres to the following guidelines:
The average user typically only reads from the catalog and rarely, if ever, writes to
it. Each user is constantly and automatically updating his or her Most Recently
Used file, but each user's "read" operations still far outweigh the user's "writes"
operations. Therefore, the read-to-write ratio is typically at least 100 to 1.
While a locking mechanism guarantees that only one user can write to an object at
a time, it is rare for multiple users to attempt to write simultaneously to the same

Configuring and Managing the Oracle BI Presentation Catalog 16-3


About the Oracle BI Presentation Catalog

object. A feature called "lazy locking" enables users to continue reading an object
even when another user is updating that object.
Modern file systems cache "small" files directly inside the directory record, such
that reading any information on a directory simultaneously loads all small files
directly into the operating system's memory cache. Therefore, it is good practice to
keep files in the catalog "small," especially the frequently "read" .atr metadata files.
When these metadata files remain small, then all the .atr files in a directory are
loaded into memory with one physical hard disk read. Every file that exceeds the
"small" threshold adds another physical hard disk read, which can cause a 100%
degradation for each large file. In other words, use care when considering storing
arbitrary "Properties" in .atr files.
Reading an object's .atr metadata file using NFS is far slower than reading it
directly from a local disk. For this reason, Presentation Services additionally
caches all .atr files internally. This cache can become briefly "stale" when another
node in the cluster writes data to the file that is newer than the data that is cached
by the current node. Therefore, all nodes are refreshed according to the
MaxAgeMinutes element in the instanceconfig.xml, whose default for a cluster is 5
minutes. This default setting commonly achieves the best trade-off between the
possibility of stale data and the known performance impact. (The default for an
environment without clusters is 60 minutes.)
You can modify the MaxAgeMinutes element for your system. Its parent elements
are Cache and CatalogAttributes.

16.1.2.2 Handling Heterogeneous Nodes


To allow heterogeneous nodes in a cluster, the catalog adheres to the following
guidelines:
The maximum length for the name of an object on disk is 256 bytes, which is 64
Unicode characters. The logical name is restricted to 256 Unicode characters. To
adhere to this restriction, logical names greater than 32 characters are hashed.
The maximum length for the name of a path on disk is 32KB, which is 8000
Unicode characters. The logical path is restricted to 16000 Unicode characters.
All path names on disk are all lowercase. The logical path name allows mixed
case, but is still case-insensitive.
Certain characters are not allowed for path names on disk, while the logical path
name allows all characters. For example, Windows systems disallow certain
characters such as the colon (:), so those characters are mapped using standard
HTML escape sequences. For example, the period character (.) becomes "%2e".
Certain file names are not allowed on disk, while the logical object name has no
restrictions. For example, Windows systems disallow certain file names such as
COM, so those names are mapped using standard HTML escape sequences. For
example, "com" becomes "co%6d".

16.1.2.3 Handling Catalog Files on Various Platforms


Keep the following points in mind when handling catalog files on various platforms:
For UNIX Platforms: UNIX kernels must commonly be configured to allow more
than 4000 subdirectories per directory. See Section 16.2.1, "Manually Changing
Configuration Settings for the Catalog" for information on the
HashUserHomeDirectories element.
For Windows Platforms:

16-4 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Maintaining the Oracle BI Presentation Catalog

When users want to navigate catalog files using a tool such as Microsoft Windows
Explorer, then they want the catalog structure based on a short path name such as
c:/obi/demo, rather than the long default path name. Note that such navigation is
not recommended.
FAT is not supported, and NTFS is required.
Performance on Windows platforms degrades noticeably when more than
8000 files exist in a single directory. Because each catalog object has two files
(the data file and the .atr metadata file), it is strongly recommended that you
not store more than 4000 catalog objects in a single directory. See
Section 16.2.1, "Manually Changing Configuration Settings for the Catalog" for
information on the HashUserHomeDirectories element.
Windows Explorer does not handle long path names properly, and it is
recommended to not use Windows Explorer to navigate the internal structure
of the catalog. While the file system can handle path names as large as 32KB
and Presentation Services is not negatively affected, you cannot use Windows
Explorer with any path name that is longer than approximately 2KB.
Because a single Unicode character can require as many as 4 bytes, you might
be unable to use Windows Explorer with path names of only 500 Unicode
characters. This limitation does not affect Presentation Services. Because of this
limitation, place the catalog in a top-level directory, such as
c:\mycatalog\sales.

16.1.2.4 Known Issues with Catalog Files


The following issues are known when working with catalog files:
Locking across NFS systems is difficult, but Presentation Services provides an
effective locking mechanism in recent versions. Obtain key patches to update
older versions of Oracle BI EE as necessary.
For more information, see Section 16.2.4, "Validating the Catalog."
Various third-party FTP programs have issues handling '%' escape sequences,
which often results in a renamed file that is doubly escaped. For example, a file
that is named sa%2epaint (whose logical name is SA.Paint) is incorrectly renamed
to sa%252epaint (whose logical name is SA%2ePaint).
Avoid using an FTP program directly against a catalog. Instead, download and use
the 7-Zip utility to compress the catalog files, then use an FTP program to transfer
the resulting compressed file.

16.2 Maintaining the Oracle BI Presentation Catalog


This section contains the following topics on maintaining a catalog:
Section 16.2.1, "Manually Changing Configuration Settings for the Catalog"
Section 16.2.2, "Deploying Catalogs and Objects to Production"
Section 16.2.3, "Updating Catalog Objects"
Section 16.2.4, "Validating the Catalog"

16.2.1 Manually Changing Configuration Settings for the Catalog


You modify settings manually using various elements in the instanceconfig.xml file to
change these settings.

Configuring and Managing the Oracle BI Presentation Catalog 16-5


Maintaining the Oracle BI Presentation Catalog

To manually change configuration settings for the catalog:


1. Open the instanceconfig.xml file for editing located in:
BI_DOMAIN/config/fmwconfig/biconfig/OBIPS
as described in Section A.1, "Configuration Files".
2. Locate the Catalog section in which you must add the following element:
HashUserHomeDirectories: Specifies the hashing of directories. If you have
more than 4000 catalog users or if you intend to have more than 4000 catalog
users in the future, then you must turn on the hashing of users' home
directories to address a file system limitation. To do so, set the
HashUserHomeDirectories element to 2 from its default value of 0. When this
element is turned on, for example, the default name for user Steve's home
directory would become /users/st/steve.

Caution: Keep the following points in mind:


Hashing is not typically needed for modern operating systems
that use modern file systems (for example, ext4, ZFS, ntfs);
however, it may still be useful for performance when your user
base exceeds approximately 4,000 users.
Oracle recommends that you hash a catalog at creation time;
however, there are circumstance that require hashing the catalog
after it is in use. Take a backup and run the following command
for more information:
On UNIX:
runcat.sh -cmd rehash -help
On Windows:
runcat.cmd -cmd rehash -help
In general, do not set the HashUserHomeDirectories element to a
value greater than 2, because a higher setting negates the
effectiveness of hashing.
Include only one Catalog element in the instanceconfig.xml file or
unexpected results might occur. Unless expressly noted, include
most nodes in an XML document only once.

3. Include the element and its ancestor element as appropriate, as shown in the
following example:
<ServerInstance>
<Catalog>
<HashUserHomeDirectories>2</HashUserHomeDirectories>
</Catalog>
</ServerInstance>

4. Save your changes and close the file.


5. Restart Presentation Services.

16-6 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Maintaining the Oracle BI Presentation Catalog

16.2.2 Deploying Catalogs and Objects to Production


You can deploy catalogs and simple objects (for example, a dashboard with privileges)
to a production environment from a test environment, as described in the following
sections:
Section 16.2.2.1, "Deploying Catalogs to Production"
Section 16.2.2.2, "Deploying Objects to Production"

16.2.2.1 Deploying Catalogs to Production


In a Windows environment, you must use the 7-Zip utility. Do not use any other
compression utility. In a UNIX environment, you can use the tape archiving (or tar)
command and a compression utility, such as GZzip, to archive an entire catalog in a
test environment. Then, you can use 7-Zip or tar to unarchive the file in the production
environment.

Caution: Do not use Catalog Manager for archiving and unarchiving


entire catalogs.
Do not use an FTP program directly against a catalog.

16.2.2.2 Deploying Objects to Production


You can deploy objects (for example, a dashboard with privileges) to a production
environment from a test environment.
To deploy catalog objects to a production environment:
1. (Optional) If you are deploying a catalog object to a new production environment.
Archive the catalog object in the test environment and unarchive it in the
production environment as follows:
a. Archive the catalog object in the test environment using one of the following:
Oracle BI Presentation Services.
Catalog Manager.
For information, see Section 16.10, "Archiving and Unarchiving Using Cat-
alog Manager."
b. Copy the archived file to the production computer.
c. On the production computer, unarchive the object.
For information about how to unarchive an object, see Section 16.10,
"Archiving and Unarchiving Using Catalog Manager."
d. Set the permissions on the object as appropriate.
2. (Optional) If you are deploying the catalog to an existing production environment.
Copy and paste new or updated objects from the test catalog into the production
catalog as follows:
a. Open two Catalog Manager windows: one with the test catalog, and another
with the production catalog.
b. Selectively copy and paste the folders from the test catalog into the production
catalog.

Configuring and Managing the Oracle BI Presentation Catalog 16-7


Maintaining the Oracle BI Presentation Catalog

If you copy and paste folders where the same content has been changed in the
test or production environments, then test content overwrites the production
content.

16.2.3 Updating Catalog Objects


If you upgrade to a newer version of Oracle Business Intelligence or install a patch and
work with objects in the catalog, then you might notice that certain objects are not
being accessed as quickly as in the previous release. This change can occur if objects
were not upgraded properly. You can confirm the need to update by viewing the
metrics in Fusion Middleware Control. In the Catalog folder, find a metric called
"Reads Needing Upgrade" with description "The number of objects read that required
upgrading." If the number is large, then you can resolve this issue by updating objects
in the catalog using the Administration page in Presentation Services.
You can upgrade to new versions of Oracle Business Intelligence by following the
instructions in Oracle Fusion Middleware Upgrade Guide for Oracle Business Intelligence.
The "Task 5: Upgrade the Oracle BI Repository and Catalog" section of that guide
contains complete information for upgrading catalog objects and describes the
recommended upgrade approach, which is to upgrade thoroughly when Presentation
Services is not running. If you suspect that the upgrading of objects was not
performed thoroughly during the upgrade process, then you can update the objects
yourself using the Administration page. The advantage of this approach is that
Presentation Services can stay up and running during the update.
Bear the following points in mind as you prepare to update objects:
If you are performing a rolling upgrade of machines in a cluster, then do not use
this option or the UpgradeAndExit configuration setting until all machines in the
cluster are upgraded.
Use this option on only one node in a cluster at a time.
To update catalog objects:
1. In the global header, click Administration.
2. Click the Scan and Update Catalog Objects That Require Updates link.
3. Click Update Catalog Objects to begin the update process.
Click the other links on the page to see which objects were updated and which
were not. You can view the log files for details on objects that were not updated.

16.2.4 Validating the Catalog


Over time, inconsistencies can develop in the catalog as links are broken, users are
deleted, or NFS file system issues are encountered. These inconsistencies can
eventually lead to incorrect behavior, such as the inability to edit an agent's recipient
list. You can periodically take the production system offline and validate the catalog, to
be informed of and to take corrective action on inconsistencies.
This section contains the following topics about validating the catalog:
Section 16.2.4.1, "Process: Validating the Catalog"
Section 16.2.4.2, "Tasks in the Validation Process"
Section 16.2.4.3, "Important Guidelines for Validating the Catalog"
Section 16.2.4.4, "Performing a Basic Validation of the Catalog"
Section 16.2.4.5, "Specifying the Elements for Validating the Catalog"

16-8 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Maintaining the Oracle BI Presentation Catalog

16.2.4.1 Process: Validating the Catalog


The process of validating the catalog involves creating a report for the catalog in
offline mode and seeing the objects that require adjustment or removal. You might fix
some objects manually in offline mode. Then run the validate operation again to allow
the system to "clean" by deleting any unnecessary objects. You repeat the process of
creating the report, manually fixing errors, and cleaning the catalog until it is
validated.

16.2.4.2 Tasks in the Validation Process


The validation process performs the following tasks:
Ensures that each object in the catalog is larger than zero bytes.
Ensures that each item in the catalog has a valid corresponding .atr file.
Ensures that each link in the catalog is valid.
Ensures that the files in the account cache are valid.
Ensures that all XML objects in the catalog pass schema validation.
Attempts to repair object names that were damaged by ftp programs.

16.2.4.3 Important Guidelines for Validating the Catalog


Before you validate the catalog, keep the following guidelines in mind:
Use care when validating a catalog in a development environment, if that
environment has a different security store from the production environment. If the
validation is performed with a different security store, then many accounts might
be removed from the catalog.
When you turn on any validation of the catalog, all ACLs (that is, all privileges
and every item's permissions) are "scrubbed," which means that dead accounts are
removed from them and any changed items are written to disk. Therefore, even if
you simply create a report without fixing any broken items automatically, you
might find that the catalog is still extensively "changed."
Before validating the catalog in a clustered environment, do one of the following:
Shut down the Presentation Services cluster and run the validation directly
against the cluster's catalog.
Make a copy of the cluster's catalog and run the validation against that copy.
Before using the 7-Zip utility to make a copy of a catalog, first shut down all
nodes in the Presentation Services cluster or put all nodes in that cluster into
Maintenance Mode (which is the recommended approach).
Be aware that any changes that are made to the catalog online concurrently to
the validation process are not included in the validation.
While backing up the catalog is always good practice, there is no practical
difference between running validate against the catalog directly versus
running the validation on a backup copy.

16.2.4.4 Performing a Basic Validation of the Catalog


You can perform a basic validation of the catalog on an ad-hoc basis as needed,
immediately before pushing content from a development environment to a production
environment, or per a regular schedule, such as on the first Tuesday of every month.
To validate the catalog:

Configuring and Managing the Oracle BI Presentation Catalog 16-9


Maintaining the Oracle BI Presentation Catalog

1. Stop Presentation Services.


For information, see Section 2.4, "Using Fusion Middleware Control to Start and
Stop BI System Component Processes."
2. Back up the catalog by using the 7-Zip utility to create a compressed file for it.
3. Create a backup copy of the instanceconfig.xml file located in:
BI_DOMAIN/config/fmwconfig/biconfig/OBIPS
4. Edit the instanceconfig.xml file so that it contains the appropriate elements for
performing the validation. You must set the elements to perform the tasks for
creating the report and "cleaning" the catalog at the appropriate times.
For information on these elements, see Section 16.2.4.5, "Specifying the Elements
for Validating the Catalog."
5. Start Presentation Services to run the validation according to the values that you
specified in the instanceconfig.xml file.
6. Edit the instanceconfig.xml file again so that it contains the appropriate elements
for performing the validation. You must set the elements to perform the tasks for
creating the report and "cleaning" the catalog at the appropriate times.
7. Repeat Steps 5 through 7 until the catalog is validated.
8. Stop Presentation Services.
9. Create a backup copy of the instanceconfig.xml file in which you added the
validation elements, renaming the file similar to instanceconfig_validate.xml. In
this way, you have a version of the file to use as a starting point for subsequent
validations.
10. Restore the backup version of the instanceconfig.xml that you created earlier to
use as the current version.
11. Start Presentation Services.

16.2.4.5 Specifying the Elements for Validating the Catalog


As part of the process of validating the catalog, you include elements in the
instanceconfig.xml file that run the validation when you restart Presentation Services.
The following procedure describes how to edit the instanceconfig.xml file to include
these elements.
To specify the element for validating the catalog:
1. Open the instanceconfig.xml file for editing, located in:
BI_DOMAIN/config/fmwconfig/biconfig/OBIPS
2. Locate the Catalog section in which you must add the elements that are described
in Table 161.
3. Include the elements and their ancestor element as appropriate, as shown in the
following example. In this example, the validation runs when Presentation
Services starts, and Presentation Services is stopped when the validation is
complete. Inconsistent accounts (such as those for deleted users), links, and objects
are removed. Inconsistent users' home directory names are logged but directories
are not removed.
<ServerInstance>
<Catalog>
<Validate>OnStartupAndExit</Validate>

16-10 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Maintaining the Oracle BI Presentation Catalog

<ValidateAccounts>Clean</ValidateAccounts>
<ValidateHomes>Report</ValidateHomes>
<ValidateItems>Clean</ValidateItems>
<ValidateLinks>Clean</ValidateLinks>
</Catalog>
</ServerInstance>

Caution: Include only one Catalog element in the instanceconfig.xml


file or unexpected results might occur. Unless expressly noted, include
most nodes (such as that for the Catalog element) in an XML
document only once.

4. Save your changes and close the file.

Table 161 Elements for Validating the Catalog


Element Description Default Value
Validate Performs the validation of the catalog according to None
the values of the other Validate-related elements in
this section. Values are described in the following
list:
None Performs no validation.
OnStartupAndExit When Presentation
Services starts, performs the validation,
performs the Report or Clean operation, then
stops Presentation Services. You run through
multiple cycles of Report, Clean, Report, and
so on for each element (such as
ValidateAccounts, ValidateHomes,
ValidateItems, and ValidateLinks) until the
catalog is validated.
If this value is not None, then all privileges and
each object's ACLs in the entire catalog are cleaned
of terminated accounts, regardless of the settings
of the other Validate-related elements.
ValidateAccounts Verifies that all information about users, roles, and None
groups in the catalog is consistent. Values are
described in the list after this table.
ValidateHomes Verifies that all information about home directories None
in the catalog is consistent. Values are described in
the list after this table.
ValidateHomes is executed only if
ValidateAccounts is set to either Report or Clean.
ValidateItems Verifies that all information about objects in the None
catalog is consistent. Values are described in the
list after this table.
ValidateLinks Cleans shortcuts in the catalog, but does not None
reconcile internal references to objects. For
example, suppose that a dashboard page includes
the text: "display the results here after running
/shared/sales/myfavreport". If a user
subsequently deletes the myfavreport object, then
no fix or message is indicated during validation.
Values are described in the list after this table.

The elements have the values that are described in the following list:

Configuring and Managing the Oracle BI Presentation Catalog 16-11


About Catalog Manager

None Specifies that no validation is performed.


Report Specifies that details about each inconsistent object are written to the
sawlog.log file.
For information, see Section 6.4.2, "What Are Diagnostic Log Configuration Files
and Where Are They Located?"
Clean Specifies that details about each inconsistent object are written to the
sawlog.log file and that each object is removed from the catalog.

16.3 About Catalog Manager


Catalog Manager is a tool that lets you perform online and offline management of
Oracle BI Presentation Catalogs. Install Catalog Manager on a secure computer that is
accessible only to Oracle BI Administrators.

16.3.1 Uses for Catalog Manager


You can use Catalog Manager to:
Manage folders, shortcuts, global variables, and objects (analyses, filters, prompts,
dashboards, and so on). For example, you can rename and delete objects, and you
can move and copy objects within and between catalogs.
View and edit catalog objects in Extensible Markup Language (XML).
Preview objects, such as analyses and prompts.
Search for and replace catalog text.
Search for catalog objects.
Create analyses to display catalog data.
Localize captions. See Section 14.2.2, "Localizing Oracle BI Presentation Catalog
Captions."
Many of the operations that you can perform in Catalog Manager can also be
performed through the Catalog page in Oracle BI Presentation Services. For
information, see "Managing Objects in the Oracle BI Presentation Catalog" in Oracle
Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

16.3.2 Guidelines for Working with Catalog Manager


Follow these guidelines when working with Catalog Manager:
Always make backup copies of the Oracle BI Presentation Catalogs that you are
working with.
Be sure of changes that you plan to make. Catalog Manager commits changes
immediately. There is no undo function nor are there any error messages to tell
you that a particular change does not display well to users. However, if you do
make any unwanted changes, then you can revert to your latest saved backup.
Do not copy and paste catalog contents into email, as this is not supported.

16.3.3 Tips for Working with Catalog Manager


As you work with Catalog Manager, keep the following tips in mind:

16-12 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Starting Catalog Manager and Opening Catalogs

While working in online mode, you can paste catalog contents into or out of a
read-only folder by turning off the read-only property of the folder tree before
copying, then re-apply the read-only attribute after pasting.
You cannot copy, archive, or drag files from the /system/security directory in the
Catalog Manager.
Some keyboard shortcuts might not work properly.
Even if a resize indicator is not shown, Catalog Manager panes might still be
resizable.
You can use Catalog Manager in languages other than English. For information,
see Section 14.3, "Setting the Current Locale in Catalog Manager."

16.4 Starting Catalog Manager and Opening Catalogs


This section describes the following topics:
Section 16.4.1, "Requirements for Running Catalog Manager"
Section 16.4.2, "Starting the Catalog Manager User Interface"
Section 16.4.3, "Resolving Startup Issues on Linux Systems"
Section 16.4.4, "Understanding the Two Catalog Modes"
Section 16.4.5, "Operations Available in Online Mode and Offline Mode"
Section 16.4.6, "Opening an Oracle BI Presentation Catalog"

16.4.1 Requirements for Running Catalog Manager


The following list describes the requirements for running Catalog Manager:
Graphical User Interface You can invoke the user interface on the following
platforms:
Windows 64-bit
Linux 64-bit
Command Line Utility You can invoke the command line utility on supported
platforms for Oracle Business Intelligence such as Windows, Linux, IBM-AIX, Sun
Solaris, and HP-UX. Enter a command such as the following one on Linux for
assistance in using the command line utility:
./runcat.sh -help

16.4.2 Starting the Catalog Manager User Interface


You can start the user interface for Catalog Manager using menu options on Windows
or a command on Windows or Linux.
To start the graphical user interface for the Catalog Manager:
1. On Windows, from the Start menu, select Oracle Business Intelligence, then
Catalog Manager.
or
Using the command line, change to the following directory:
BI_DOMAIN\bitools\bin

Configuring and Managing the Oracle BI Presentation Catalog 16-13


Starting Catalog Manager and Opening Catalogs

then run the appropriate script:


runcat.cmd (on Windows)
runcat.sh (on Linux)
Figure 162 shows sample objects in the Catalog Manager for Windows platforms.

Figure 162 Sample Objects in Catalog Manager for Windows

16.4.3 Resolving Startup Issues on Linux Systems


You must start the Catalog Manager in a graphical user interface xterm on Linux
systems. Examples of xterms are a native gnome, kde console, VNC, or a local x-server
such as Xming, Tarantella, Hummingbird Exceed, or Citrix. (These examples do not
constitute a statement of certification or support.) You cannot start the graphical user
interface for Catalog Manager using an ASCII text terminal, such as PuTTy or FSecure
or a command-line SSH.
If the Catalog Manager does not start, then verify the following:
That you can run a native application such as xclock or xeyes.
That you can start Catalog Manager with a native console or with VNC.
Sometimes operating system administrators can lock X-Windows.
That you can run the following command, which allows all xterm connections:
xhost +
That you can run Catalog Manager from the command line with debugging
enabled to see if any additional output is produced, using the following
command:
./runcat.sh -consoleLog -noExit
That you can use an operating system utility such as strace to trace the execution
of the runcat.sh command and see if any error messages are generated, such as
those relating to libraries or files being unable to open. You can use the Eclipse
Java plug-in that requires the standard widget toolkit (SWT), which in turn
requires GTK (Gimp Toolkit) to be installed. Enter the following command:
strace -aef -o ./runcat_trace.txt runcat.sh

16-14 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Starting Catalog Manager and Opening Catalogs

16.4.4 Understanding the Two Catalog Modes


You can open a catalog in one of two modes online or offline. Both modes can
operate against an actual production catalog, with no need for any downtime.

16.4.4.1 Online Mode


In online mode, you connect to a catalog on a running web server. In this mode your
permissions are applied, you can select a locale, and you can see the effects of any
localization on the catalog. You can see only those objects for which you have the
appropriate permissions. Both Presentation Services and the web server must be
running for you to open catalogs in online mode.
Use online mode when you want to make minor incremental changes or additions to
the catalog, such as changes to permissions, updates to a single object, or migration of
new objects to a production environment.

16.4.4.2 Offline Mode


In offline mode, you connect to a local file system. In this mode, you are logged in as a
super user or system user, and no permissions are applied. You can see all objects in
the catalog.
Generally, working in offline mode is faster than working in online mode. This is
because you are accessing, creating, and updating the individual files directly, and the
catalog does not have to communicate with Presentation Services as it does when you
are working in online mode.
Use offline mode when you want to make catalog-wide changes, such as globally
renaming objects or moving multiple objects for reorganization, as described in the
following procedure.
To make systemwide changes to the catalog:
1. Place Presentation Services in Maintenance Mode.
In a clustered environment, you can place any instance of Presentation Services in
Maintenance Mode and within a few minutes, all other instances in the cluster
automatically go into Maintenance Mode too. In a clustered environment only,
wait a few minutes before performing the tasks for which you placed Presentation
Services into Maintenance Mode.
For information on Maintenance Mode, see "Administration page" in Oracle Fusion
Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.
2. Back up the catalog by using the 7-Zip utility to create a compressed file for it.
3. In Catalog Manager, open the catalog in offline mode, as described in
Section 16.4.6, "Opening an Oracle BI Presentation Catalog."
4. Make the systemwide change.
5. Back up the catalog again.
6. Take Presentation Services out of Maintenance Mode.
In a clustered environment, you can take any instance of Presentation Services out
of Maintenance Mode and within a few minutes, all other instances in the cluster
automatically go out of Maintenance Mode too. So in a clustered environment
only, a few minutes are required before users can resume editing catalog content.

Configuring and Managing the Oracle BI Presentation Catalog 16-15


Starting Catalog Manager and Opening Catalogs

16.4.5 Operations Available in Online Mode and Offline Mode


Many of the operations that you can perform using Catalog Manager are available in
both online mode and offline mode. A few operations are available in only one mode
or the other. Generally, the operations available in:
Online mode are read-only operations and write operations that do not affect the
entire catalog, such as setting permissions for an object.
Offline mode include most of the operations available in online mode and write
functions that affect the entire catalog.
You can perform the following operations in online and offline modes (or as stated), as
follows:
Cutting objects.
Copying objects.
Pasting objects.
Copying objects for another catalog.
Pasting objects from another catalog.
Creating shortcuts of objects.
Deleting objects.
Renaming objects without reference updates.
Renaming objects with reference updates. (This feature is known as Smart Rename
and is available in both modes. In offline mode, you can rename all objects. In
online mode, you might be unable to rename certain objects, depending on your
permissions.)
Refreshing the Catalog Manager workspace.
Creating folders.
Setting permissions for objects.
Working with properties of objects.
Managing the view of the workspace.
Searching for objects.
Searching for and replacing catalog text. (This feature is available in both modes.
In offline mode, you can replace all objects. In online mode, you might be unable
to replace certain objects, depending on your permissions.)
Creating reports to display Catalog Manager data.
Setting browser preference.
Previewing objects (available in online mode only).
Exporting captions for localization purposes.

16.4.6 Opening an Oracle BI Presentation Catalog


To open an Oracle BI Presentation Catalog:
1. In Catalog Manager, from the File menu, select Open Catalog.
2. Complete the necessary fields, as described in the following list:
Type Select the mode (online or offline) in which to open the catalog

16-16 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Using the Catalog Manager Workspace

Path If you are opening the catalog in offline mode, then enter the path to
the catalog folder on the local file system, for example:
Click Browse to display a dialog for locating the catalog.
SDD/metadata/content
Where SDD is the Singleton Data Directory for example, DOMAIN_
HOME/bidata (for more information, see Section 1.4, "Key Directories in
Oracle Business Intelligence").
URL If you are opening the catalog in online mode, then enter the URL to
Oracle BI Presentation Services, for example:
https://hostname/analytics/saw.dll
User If you are opening the catalog in online mode, then enter the user
name for the host URL (disabled in offline mode).
Password If you are opening the catalog in online mode, then enter the
password for the host URL (disabled in offline mode).
Locale Select the locale to use for user interface elements in Catalog
Manager and for objects in the catalog, when opening the catalog in online
mode.
Read-Only Select this field to open the catalog in read-only mode (disabled
in offline mode).
3. Click OK.
When specifying the URL for the catalog in online mode, ensure that you specify
https rather than http, for increased security. If you specify http, then you see a
message box after closing the Open Catalog dialog that prompts you to verify the
opening of the catalog using an unsecured connection. To use https when opening
catalogs, you must configure Oracle BI EE for Secure Socket Layer communication, as
described in "SSL Configuration in Oracle Business Intelligence" in Oracle Fusion
Middleware Security Guide for Oracle Business Intelligence Enterprise Edition.

16.5 Using the Catalog Manager Workspace


This section provides the following topics on the workspace for Catalog Manager:
Section 16.5.1, "What Does the Catalog Manager Workspace Do?"
Section 16.5.2, "What Does the Catalog Manager Workspace Look Like?"
Section 16.5.3, "Managing the View of the Catalog Manager Workspace"

16.5.1 What Does the Catalog Manager Workspace Do?


The Catalog Manager workspace enables you to view and work with catalog objects. It
displays the following folders for an open catalog:
The shared folder Contains content that is shared among catalog users. This
includes the preconfigured dashboards and analyses that are distributed with
prebuilt applications, and other objects such as shared filters.
The system folder Contains administrative elements of Presentation Services.
Some of these elements are distributed with the product, and others are
configured by you as the administrator, such as privileges. Avoid modifying any
files in this folder. Presentation Services uses these files internally and modifying
them might cause unexpected results.

Configuring and Managing the Oracle BI Presentation Catalog 16-17


Using the Catalog Manager Workspace

The users folder Contains content that catalog users with the appropriate
permissions have saved to their personal folders, such as individual analyses.

16.5.2 What Does the Catalog Manager Workspace Look Like?


Catalog Manager consists of the following main components:
Menu bar Lets you access the following menus:
File Provides options that let you open and close catalogs, exit Catalog
Manager, and so on.
Edit Provides options that let you manage catalog objects, such as Cut,
Copy, Permissions, and so on. (Many of these options are also available on the
right-mouse menu.)
View Provides options to manage the view of the Catalog Manager
workspace, such as Show Tree, Show Job Status, and so on.
Tools Provides options that let you manage catalogs, such as XML Search
and Replace, Create Report, and so on.
Help Provides options to access the Oracle BI Enterprise Edition website
and to display information about Catalog Manager.
Toolbar Provides quick access to commonly used options, such as Cut, Copy,
Paste, and so on.
Tree pane Displays catalog folders. The pane also displays objects but only if
the Show Objects in Tree option on the View menu is selected.
Table pane Displays catalog folders and objects. It consists of:
The navigation bar, where you can move to the catalog object to work with by
typing its path name.
These columns: Name, Type, Owner, My Permissions, Attributes, Date
Created, and Last Modified. Click the column name to sort by that value, such
as by type.
The Type column identifies the type of object. Objects that are identified as
"unknown file" are generally internally used objects, and their type is not
exposed in Catalog Manager.
Right-mouse menu Provides options that let you manage catalog objects, such
as Rename, Properties, Permissions, and so on. (Many of these options are also
available on the Edit menu.)

16.5.3 Managing the View of the Catalog Manager Workspace


You can manage what you view in the Catalog Manager. For example, you can show
objects in the Tree pane or show job statuses.
To manage the view of the Catalog Manager workspace:
1. In Catalog Manager, select View and then one of these options:
Show Tree Displays the Tree pane, if you previously had closed it.
Show Table Displays the Table pane, if you previously had closed it.
Show Job Status Displays the Background Job Status pane, where you can
view the progress of processes that you have run, such as Search and Replace,

16-18 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Working with Objects in Catalog Manager

Smart Rename, and so on. You can also remove all finished jobs and set
progress preferences using the icons in the upper-right corner of the pane.
Show Objects in Tree Displays objects (that is, analyses, filters, and so on)
in addition to folders in the Tree pane.
Refresh Refreshes the objects that are displayed in the Tree and Table
panes. (You might want to refresh the data, for example, if someone else
makes changes to the catalog while you are working with it and you want to
see the changes.)

16.6 Working with Objects in Catalog Manager


This section provides the following information about working with objects:
Section 16.6.1, "Searching for Catalog Objects Using Catalog Manager"
Section 16.6.2, "Copying and Pasting Objects"
Section 16.6.3, "Renaming Catalog Objects"
Section 16.6.4, "Working with the Properties of Catalog Objects"
Section 16.6.5, "Setting Permissions of Catalog Objects"
Section 16.6.6, "Previewing Objects from Catalog Manager"
In the Catalog page of Presentation Services, you can view folders and contents
including hidden objects. You can create, rename, copy, move, and delete folders and
contents. For more information, see "Managing Objects in the Oracle BI Presentation
Catalog" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence
Enterprise Edition.

Note: Changes made in the Presentation layer of the Oracle BI


Administration Tool can affect analyses and dashboards based on
those tables and columns. You can use Catalog Manager to keep the
catalog synchronized with these changes in the Presentation layer.

16.6.1 Searching for Catalog Objects Using Catalog Manager


You can search for objects in the catalog using the Search function. For example, you
might want to search for all objects that have a property with the value of
"administrator."
When you search, you can limit the search by:
Case Sensitive Select this check box to apply case sensitivity to the search
criteria. The default value is unchecked.
Name Limits the search to the names of objects.
Description Limits the search to the Description property.
Property values Limits the search to the values of properties.
Owner Limits the search to the owners of objects.
XML Limits the search to XML.
Object type Searches for all types of objects or limits the search to a specific type
of object that you specify (for example, analyses, filters, agents, dashboard
prompts, dashboard pages).

Configuring and Managing the Oracle BI Presentation Catalog 16-19


Working with Objects in Catalog Manager

Date Limits the search to objects that were created on the dates that you specify
or to objects that were last modified on the dates that you specify.
To search for an object:
1. In Catalog Manager, open the catalog and navigate to the location in the tree
where you want to begin the search.
2. Click Search on the toolbar.
3. In the Search for any or all criteria below field, enter the word or phrase to search
for.
4. To make the search case-sensitive, select the Case Sensitive box.
5. To limit the search, then click Advanced Search.
6. In the Advanced Search area, specify the constraints for the search.
7. Click Search.

Tip: When you have finished searching, click Explore the entire
catalog tree on the toolbar to return to the Tree and Table panes.

16.6.2 Copying and Pasting Objects


You can copy and paste objects within a single catalog. You can also copy objects from
one catalog and paste them into another catalog.

16.6.2.1 Tips for Copying and Pasting


Use the following tips as you copy and paste objects:
You can copy and paste objects using the following methods:
Menu options, as described in Section 16.6.2.1.1, "Copying and Pasting Objects
Between Catalogs Using Menus."
Drag and drop, to copy objects between two catalogs and within the same
catalog. Drag and drop always makes a copy of the dragged objects, even
when performing a drag and drop within a single catalog.
Archive and unarchive, as described in Section 16.10, "Archiving and
Unarchiving Using Catalog Manager." When you archive, you create a file that
you can save for later use. The unarchiving process automatically overwrites
any files without providing the opportunity to specify that certain files not be
overwritten.
Catalogs are structured in hierarchical folders. When copying or merging objects,
remember to also copy any objects that are associated with them, such as
dashboard folders, shortcuts, and analyses. URL paths in external applications can
be reestablished after a copy or merge operation if the entire folder path is not
copied, for example, if added to the dashboard as a shortcut or text.
Most often, you can simply copy and paste objects as needed. If required, you can
set advanced options that affect the objects that you are pasting. For complete
information, see Section 16.6.2.2, "Advanced Options for Pasting Objects."

16.6.2.1.1 Copying and Pasting Objects Between Catalogs Using Menus The following
procedure describes how to copy and paste objects between two catalogs using menu
options. If the two catalogs have the same name, then you might want to rename one
of the catalogs before opening it to help distinguish between the two catalogs as you
work. Both catalogs must be the same version 11.1.1 (or later).

16-20 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Working with Objects in Catalog Manager

To copy and paste objects between catalogs using menus:


1. In Catalog Manager, open the catalog to change, that is the target catalog.
2. Using another instance of the Catalog Manager, open the catalog that contains the
objects to copy, that is the source catalog.
3. If necessary, reposition both instances of Catalog Manager on your screen so you
can display the title bars of both Catalog Manager instances.
4. In the Catalog Manager instance that shows the source catalog, right-click the
source object and select Copy.
5. In the Catalog Manager instance that shows the target catalog, right-click at the
point where you want to paste the source object and select Paste.

16.6.2.2 Advanced Options for Pasting Objects


You can set advanced options in the Preferences dialog for pasting objects that you
have copied, as described in the following sections:
Section 16.6.2.2.1, "Paste Overwrite"
Section 16.6.2.2.2, "Paste ACL"

Important: You must set the advanced options in the Preferences


dialog before you begin the copy and paste operation, for them to take
effect.

16.6.2.2.1 Paste Overwrite The Preferences dialog contains the following options in the
Paste Overwrite area:
Force Pastes all files, overwriting even those that have the read-only attribute
set.
All Pastes all possible files, overwriting only those that do not have the
read-only attribute set. (Default)
Old Pastes all possible files, but does not overwrite any existing files unless
they are older than the source.
None Pastes all possible files, but does not overwrite any existing files.
Consider the following example of pasting with overwrite options set. Suppose that
the /users/joe folder contains the following analyses:
Analysis A (created 01-Jan-2010)
Analysis B (created 31-May-2010)
Analysis C (created 01-Jan-2010)

Suppose that the /users/sue folder contains the following analyses, but no Analysis C
Analysis A (created 28-Feb-2010)
Analysis B (created 01-Jan-2010)

Suppose that Sue copies the A, B, and C Analyses from the /users/joe folder and
pastes them to the /users/sue folder. If the Paste Overwrite option is set to:
None, then Sue keeps her A and B Analyses, and Joe's analyses are ignored. Sue
gets a copy of Analysis C.

Configuring and Managing the Oracle BI Presentation Catalog 16-21


Working with Objects in Catalog Manager

All, then Sue's A and B Analyses are overwritten with Joe's, and Sue gets a copy of
Analysis C.
Old, then Sue keeps her A Analysis (Sue's A Analyses is not "old"), Sue's B
Analysis gets overwritten by Joe's analysis (Sue's B Analysis was "old"), and Sue
gets a copy of Analysis C.

16.6.2.2.2 Paste ACL The Preferences dialog contains the following options in the Paste
ACL area:
Inherit Inherits the object's permissions (ACL) from its new parent folder.
(Default)
Preserve Preserves the object's permissions (ACL) as it was in the original,
mapping accounts as necessary.
Preserve Only Groups Same as Preserve, but applies to group accounts and
Application Roles, not to user accounts. This is for a development to production
environment in which a customer might use the same groups (such as Sales and
Marketing) in both development and production. However, the users in each
group might be very different, such as TestUserA and TestAdminB in
development and Steve and Sue in production.
Create Preserves the object's permissions (ACL) as it was in the original,
creating and mapping accounts as necessary, depending on the mode and type of
owner, as described in the following list:
Online mode In online mode, Catalog Manager is communicating with the
back-end security server. Catalog Manager knows about the users and
application roles from that server and can usually paste a copied object with
the appropriate user name or role. While pasting objects, keep in mind that
you might lack appropriate permissions to create accounts for certain objects.
Offline mode In offline mode, Catalog Manager has no connection with the
back-end security server, so it is unaware of users and application roles that
are stored there, unless their names are available in the cache for the catalog. If
the name of the user or role for a copied object is not available in the cache,
then Catalog Manager cannot paste the copied object with that name or role.
Instead, the pasted object inherits its owner from its new parent folder, which
is similar to the Inherit option.
However, because Catalog groups are stored in the catalog rather than in the
back-end security server, then Catalog Manager can associate Catalog groups
with pasted objects as appropriate.
This feature is used in applications whose administrators create accounts in a
staging area before moving the users to the production environment.
Create Only Groups Same as Create, but applies only to Catalog groups, not to
user accounts. Works in a development to production environment similarly to
Preserve Only Groups.
If you have the appropriate permissions, then you can select a newly pasted object and
set ownership recursively to the appropriate user.
Consider the following example of pasting with ACL options set. Suppose that Steve
owns the /users/steve/MyFavReport folder and has permissions (ACL) "all users can
read/execute, steve has full control". Joe (who has some administration privileges)
logs in and copies MyFavReport, pasting it to /users/sue (which is owned by
"administrator", with permissions "admins have full control, sue has full control").
If Joe sets the Paste ACL option to:

16-22 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Working with Objects in Catalog Manager

Inherit, then the /users/sue/MyFavReport folder is owned by Joe with whatever


permissions are set on the /users/sue folder (that is, "admins have full control, sue
has full control").
Preserve, then the /users/sue/MyFavReport folder is owned by Joe with
whatever permissions were set on the /users/steve/MyFavReport folder (that is,
"all users can read/execute, steve has full control"). If Joe pastes in a second
Catalog Manager and if "steve" does not exist in this Catalog, then the permissions
for Steve are discarded. If "steve" exists but has a different user ID, then Steve's
user ID is mapped to the new one.
Create in online mode, then the /users/sue/MyFavReport folder is owned by Joe
with whatever permissions were set on the /users/steve/MyFavReport folder
(that is, "all users can read/execute, Steve has full control"). If Joe pastes in a
second Catalog Manager and if "steve" does not exist in this catalog, then the
owner is inherited from the parent folder. (The Create option is deprecated in
Release 11g as it applies only to Catalog groups.)

16.6.3 Renaming Catalog Objects


You can rename objects in the catalog. This can be useful when you are migrating from
a test environment to a production environment.
There are two ways to rename an object:
Rename without reference updates Renames the object and preserves the
references to the original name that other catalog objects might have.
Rename with reference updates Renames the object and changes references that
other objects might have to the new name (that is, original name references are not
preserved). This feature is also known as Smart Rename. You can open the catalog
in either offline or online mode. In offline mode, you can rename all objects. In
online mode, you might be unable to rename certain objects, depending on your
permissions.

Caution: Keep the following points in mind when renaming objects:


You cannot rename a user account in the catalog. If you rename a
user's home directory, then you do not rename that user and you
might see unexpected results.
The catalog contains several reserved names of objects. Rename
only your own objects, not those that Presentation Services creates
internally. For example, do not rename the _portal directory in
your home directory, because then you cannot see "My
Dashboard".

To rename an object without reference updates:


1. In Catalog Manager, open the catalog.
2. Navigate to the object to be renamed.
3. Right-click the object in the Name column and select Rename.
4. Type a new name for the object.
To rename an object with reference updates:
1. In Catalog Manager, open the catalog in offline mode.

Configuring and Managing the Oracle BI Presentation Catalog 16-23


Working with Objects in Catalog Manager

2. Navigate to the object to be renamed.


3. Right-click the object in the Name column and select Smart Rename.
4. Type a new name for the object.
A progress bar in the lower-right corner of the window shows the progress of the
reference updates.

16.6.4 Working with the Properties of Catalog Objects


Using the Properties option of Catalog Manager, you can:
Create, view, edit, and delete the properties of catalog objects.
Change attributes of catalog objects to hide them from display in Oracle Business
Intelligence.
To work with the properties of a catalog object:
1. In Catalog Manager, open the catalog.
2. Navigate to the object.
3. Right-click the object in the Name column and select Properties.
4. Perform the necessary tasks:
a. If you have the appropriate permissions, then select the appropriate owner for
the object in the Owner list.
The Owner list includes the name that you used to log in to Catalog Manager.
You can use this list to select yourself as the owner of the object.
See "Assigning Ownership of Objects" in Oracle Fusion Middleware User's Guide
for Oracle Business Intelligence Enterprise Edition for more information on taking
ownership of objects.
b. To change the attribute of an object, select either Read-Only or Hidden, if
appropriate. A hidden object is not visible in Oracle Business Intelligence.

Note: The System option indicates that the object is maintained


internally and should not be altered.

c. To create, edit, or delete a property, use the New, Edit, or Delete button as
appropriate.

Note: The New button is used to create a property. Use it only if


instructed to do so by Oracle Support Services.

5. Click OK.
You can select multiple objects and update their properties or permissions
simultaneously. If any of the selected objects are a folder, then you can also apply those
changes recursively to all the objects in that folder's tree structure.
For example, you can set all files in the /shared/DontTouch directory to be Read-Only.
Right-click the DontTouch directory and select Properties. In the Properties dialog,
select the Read-Only option, select the Apply Recursively option, and click OK. You
can also select Apply Recursively to take ownership of an object and all its
sub-objects.

16-24 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Working with Objects in Catalog Manager

16.6.5 Setting Permissions of Catalog Objects


Permissions are used to control access to catalog objects.
To set permissions of a catalog object:
1. In Catalog Manager, open the catalog.
2. Navigate to the object.
3. Right-click the object in the Name column and select Permissions.
The Permissions dialog displays these two lists:
Users, Catalog Groups and Application Roles (Explicit Permissions)
Shows the users, groups, and application roles that have explicit permissions
granted to this object.
Additional Users and Application Roles Shows the users, groups, and
application roles that have access granted through group inheritance, and
users, groups, and application roles that have no access to the request.
For details on how permissions and privileges are assigned in Presentation
Services, see "Managing Security for Dashboards and Analyses" in Oracle Fusion
Middleware Security Guide for Oracle Business Intelligence Enterprise Edition.
4. If the user, group, or application role whose permissions you want to set is in the
Additional Users and Application Roles list, then move it into the Users, Catalog
Groups and Application Roles (Explicit Permissions) list by selecting it and
clicking the left-arrow button (<).
5. (Optional) To filter the users, groups, and application roles displayed in the
Additional Users and Application Roles list, use the List button and the adjacent
field, as follows:
Enter filter criteria in the field next to the List button (case insensitive) to
search by name.
To enter partial filter criteria, use the asterisk (*) symbol. For example, enter
bi* to display users or groups beginning with bi, BI, bI, and Bi.
Select a value from the list, to restrict what accounts to search for.
Available values are: All, User, Catalog Group, or Application Role.
6. Select the user or group in the Users, Catalog Groups and Application Roles
(Explicit Permissions) list.
7. Select a new permission from the list in the Permissions column, or click Custom
from the list to display the Custom Permissions dialog, where you can select a
combination of permissions.
For details on what each permission means, see "Permission Definitions" in Oracle
Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.
8. Select the Apply Recursively option to apply the changes to all the objects that the
object contains.
9. Select a value from the Replace Option list as follows:
Replace All Replaces the existing ACL with what is currently in the dialog.
Replace Listed Changes only the accounts currently displayed in the dialog
and leaves others unchanged.
Remove Listed Removes only the accounts currently displayed and leaves
others unchanged.

Configuring and Managing the Oracle BI Presentation Catalog 16-25


Viewing and Editing Catalog Objects in XML

10. Click OK.

Note: If you move a user or group from the Users and groups
(Explicit Permissions) list to the Additional Users and Application
Roles list, then the user or group privileges are reset to No Access. To
move a user or group from one list to another, highlight it and click
the right or left-arrow button, as appropriate.

See Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise
Edition for more information about permissions and groups and users.

16.6.6 Previewing Objects from Catalog Manager


You can preview objects, such as analyses or prompts, from Catalog Manager in online
mode. If you are going to preview objects from Catalog Manager, then you must
identify the default browser in which to display these objects.
To set the browser preference:
1. In Catalog Manager, from the Tools menu, select Preferences.
2. In the Select Web Browser to use for report previews field, select the browser that
is the same one that you have set to be the default browser for your operating
system. You can click the Browse button in which you can select the executable file
for the appropriate browser.
3. Click OK.
To preview an object:
1. In Catalog Manager, open the catalog in online mode.
2. Navigate to the object.
3. Right-click the object in the Name list and select Preview.

16.7 Viewing and Editing Catalog Objects in XML


Catalog Manager provides the ability to view and to edit the XML description of
catalog objects such as analyses, dashboards, filters, and so on. While viewing the
XML code is acceptable, editing the code is not recommended.

Caution: If you edit the XML code, then you change the
representation of the object in the catalog. Editing the XML code for
catalog objects in any directory is not recommended and can produce
unexpected results
If you want to edit the XML for an analysis, then use the information
in "Examining the Logical SQL Statements for Analyses" in Oracle
Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise
Edition.

To view the XML description of an object:


1. In Catalog Manager, open the catalog.
2. Navigate to the object.

16-26 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Viewing and Editing Catalog Objects in XML

3. Right-click the object in the Name column and select Properties.


4. Click Edit XML.
5. When you have finished viewing the XML definition, click Cancel.
6. Click OK in the Properties dialog.
Figure 163 shows sample XML code in Catalog Manager for an object.

Figure 163 Sample XML Code for an Object

To edit the XML description of an object, which is not recommended:


1. In Catalog Manager, open the catalog.
2. Navigate to the object.
3. Right-click the object in the Name column and select Properties.
4. Click Edit XML, then Edit.
5. Make the changes in the Object XML area.

Configuring and Managing the Oracle BI Presentation Catalog 16-27


Searching for and Replacing Catalog Text Using Catalog Manager

Note: When you edit the XML description of an object, the catalog
checks only that the XML is well-formed; it does not check for any
other errors.

6. Click OK in the Edit XML dialog.


7. Click OK in the Properties dialog.

16.8 Searching for and Replacing Catalog Text Using Catalog Manager
You can search for specific text in the catalog and replace it with other text using
Catalog Manager. You can open the catalog in either online or offline mode. In offline
mode, you can replace all objects. In online mode, you might be unable to replace
certain objects, depending on your permissions.
Specifically, you can search for and replace:
A simple text string using a dialog, as described in Section 16.8.1, "Searching for
and Replacing a Simple Catalog Text String."
For example, suppose that an object contains the string "My Misspeled Wirds."
You can use Catalog Manager to search and replace that string with the proper text
of "My Misspelled Words."
Multiple or complex text strings all at the same time using an XML file, as
described in Section 16.8.3, "Searching for and Replacing Multiple Catalog Text
Strings."
For example, suppose that the administrator renames a subject area, a table, or
column in the repository file. The table "Sales" might be renamed "MySales." You
can use Catalog Manager to search and replace all uses of that object throughout
the catalog.

16.8.1 Searching for and Replacing a Simple Catalog Text String


Use the following procedure to search for a simple text string in the catalog and
replace it with other text.
To search for and replace a simple text string:
1. In Catalog Manager, open the catalog in either online or offline mode.
2. From the Tools menu, select XML Search and Replace.
3. In the Old text field, enter the text string to search for.
4. In the Replace with field, enter the replacement text.
5. To make the search case insensitive, deselect the Case Sensitive box.
6. Click OK.

16.8.2 About Searching for and Replacing Multiple Catalog Text Strings
You can perform more powerful search and replace operations on multiple catalog text
strings all at the same time by importing a XML file that identifies each text string to
search for and replace.

16-28 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Searching for and Replacing Catalog Text Using Catalog Manager

16.8.2.1 XML File Format for Searching for and Replacing Text Strings
In the search and replace XML file, you use an action element to identify each text
string to search for and replace. The action elements are contained in a commands
element.
The action element has the following attributes:
command Specifies the text to replace. The valid value is:
textReplace Replaces all the text that matches in an XML file, such as a
column name.
oldValue Specifies the text string to search for.
When you specify this attribute for the textReplace command for the search and
replace XML file, you must use the full Java regex syntax, which is not like a
normal string. To replace a string, you must do the following:
1. Escape any special Java regex characters (such as brackets, parentheses, dollar
signs, and carets).
2. Escape any special "normal" string characters (such as back slashes and
quotes).
3. Because you are working in an XML file, escape any special HTML characters
(such as quotes and ampersands).
The full Java regex syntax is described in the following document:
http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html
Table 162 provides sample strings for use with the regex syntax in search criteria.

Table 162 Sample Strings For Use With Regex Syntax in Search Criteria
Search String Entered Result
a Adds wildcards before and after your search string (for
example, *a*), enabling the search to return results that contain
the letter "a".
^a Adds a wildcard after your search string (for example, a* ),
enabling the search to return results that begin with the letter
"a".
a$ Adds a wildcard before your search string (for example, *a ),
enabling the search to return results that end with the character
"a".
a\* Searches explicitly for strings containing a character followed
by an asterisk (*) for example, "a*".
? Use a question mark (?) with a character and an asterisk (*) to
return zero (0) or more occurrences of a character. For example
?a* returns zero or more occurrences of the character "a".

newValue Specifies the replacement text.


ignoreCase Ignores case when set to true, but becomes case-sensitive when set
to false. The default value is false.

16.8.2.2 Example XML File for Searching for and Replacing Text Strings
The following is a partial example of an XML file for searching for and replacing a text
string:
<?xml version="1.0" encoding="utf-8"?>

Configuring and Managing the Oracle BI Presentation Catalog 16-29


Creating Reports to Display Catalog Data Using Catalog Manager

<actions>
<action command="textReplace" oldValue="boots" newValue="HoleyShoes"
ignoreCase="true"/>
</actions>

16.8.3 Searching for and Replacing Multiple Catalog Text Strings


Use the following procedure to search for and replace multiple catalog text strings all
at the same time.
To search for and replace multiple text strings:
1. Create the XML file for searching for and replacing multiple text strings.
For information, see Section 16.8.2, "About Searching for and Replacing Multiple
Catalog Text Strings."
2. In Catalog Manager, open the catalog in offline mode.
3. From the Tools menu, select XML Search and Replace.
4. In the Import from File field, enter the path or click Browse to specify the XML
file that you created in Step 1.
5. To make the search case-sensitive, select the Case Sensitive box.
6. Click OK.

16.9 Creating Reports to Display Catalog Data Using Catalog Manager


You can create reports to display catalog data for all catalog object types. You can
either display the report on the screen or save it to a file. When you create a report, a
blank or empty field is exported as a tab character. If you create a report with the
default of a tab as the field separator, then two tab characters in the report file indicate
a blank field.
To create a report that displays catalog data:
1. In Catalog Manager, open the catalog. To create a report that shows the SQL
statement that is sent to the Oracle BI Server for the object, open the catalog in
online mode.
2. Select the top folder for the catalog.
3. From the Tools menu, select Create Report.
4. Select the catalog object type for which you want to create a report.
5. To eliminate any rows that are the same from the report, select the Distinct box.
6. Specify the columns to be displayed in the report in the Columns in Report list.
Use the left and right-arrow buttons (< and >) to move the columns between the
Available Columns list and the Columns in Report list, and the plus and minus
buttons (+ and -) to set the order in which columns are displayed in the report.
7. Click OK.
8. Repeat Steps 4 through 7 until the report contains the appropriate columns.
9. To save the report to a file, in the Save report to field, specify the path name of the
file. Click the Browse button to display the Save As dialog for selecting the path
name (if the file does not exist, then it is created).
10. Select Excel Format to specify to create a file with a .tab extension that can be
imported into Microsoft Excel.

16-30 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Archiving and Unarchiving Using Catalog Manager

For details on supported Excel versions as part of Microsoft Office, see the system
requirements and certification documentation. For information, see Section 1.9,
"System Requirements and Certification."
11. Click OK.

16.9.1 Sample Uses for Reports


You can generate reports for various purposes, as described in the following examples:
To see which dashboards are using an analysis, you can run a Dashboard report
including analyses, and search that report for the analysis
To find analyses that are affected by a changed column in a repository table, you
can run an Analysis report that includes all columns and formulas, and then
search the report for the items that must then be replaced in Catalog Manager.
You can create a report that displays all the dashboard prompts and related fields
(such as column, formula, and subject area) within the dashboards. You can also
create a report of analyses and extract the filters that are used within those
analyses. The following is an example of extracting filters in which the formula is
derived using a saved filter that is prompted:
Example: "Markets"."Region" [Filter, prompted]
You can create a report that displays the ACLs for objects. By reviewing the ACLs
in the report, you can verify that access to objects is granted to the proper roles
with the proper permissions, such as Read/Write. The following line shows an
example of ACLs in the report:
"^biconsumer=RX:*MyCatalogGroup=RWX:steve=F", where the caret (^) indicates
an Application Role, the asterisk (*) indicates an internal catalog group, and
"nothing" indicates a user.

16.10 Archiving and Unarchiving Using Catalog Manager


Catalog Manager provides the ability to archive and unarchive either an individual
catalog folder or an entire catalog. See the following list for important information on
this functionality:
When you archive an individual catalog folder, all objects in the folder and the
folder's subfolders are saved in single compressed file. Properties and attributes of
objects are included in the archive file.
When you unarchive an individual catalog folder, the archive file is uncompressed
and all objects in the folder and the folder's subfolders are then stored in the
current offline catalog. Existing folders that have the same names as folders being
unarchived are overwritten without warning.
Archiving and unarchiving an entire catalog using Catalog Manager or the
Catalog page in Presentation Services is not recommended. Instead, use either the
7-Zip utility or .tar.gz files on UNIX systems for archiving and unarchiving an
entire catalog.
Do not archive an entire catalog by starting at the root level (\). Always specify
specific folder names when archiving.
Do not use the following utilities when archiving and unarchiving an entire
catalog:

Configuring and Managing the Oracle BI Presentation Catalog 16-31


Archiving and Unarchiving Using Catalog Manager

WinZip The WinZip utility does not always handle extended UNIX file
permissions properly. Using the WinZip utility to move catalogs in
heterogeneous environments might lead to corrupted catalog files.
FTP Some third-party FTP programs rename internal files, which might
lead to corrupted catalog files. Before moving a catalog using an FTP program,
use the 7-Zip utility to compress the catalog into one file.
You can use the Catalog page in Presentation Services to archive and unarchive
objects. For information, see "Archiving Objects" in Oracle Fusion Middleware User's
Guide for Oracle Business Intelligence Enterprise Edition.

16.10.1 Archiving a Folder Using Catalog Manager


Use the following procedure to archive a catalog folder.
To archive an individual catalog folder in the catalog to a file that you specify:
1. In Catalog Manager, open the catalog in offline mode.
2. Highlight the catalog folder and from the File menu, select Archive.
3. In the Archive File Path field, specify the path name of the file in which to archive
the folder. Click Browse to display a dialog for selecting the path name.
4. To archive the:
Timestamps that are assigned to the objects and folders that you are archiving,
then select the Keep file time stamps option.
If you do not select this option, then the archiving process does not include
timestamp information and the Old option in the Paste Overwrite area of the
Preferences dialog is ignored. Upon unarchiving, the system applies a
timestamp that indicates the time at which the object or folder is unarchived.
See Section 16.6.2.2, "Advanced Options for Pasting Objects" for more
information.
Permissions that are assigned to each object or folder, then select the Keep
permissions option.
If you do not select this option, then the archiving process does not include
any permissions and the options in the Paste ACL area of the Preferences
dialog are ignored. Upon unarchiving, the system assigns the parent folder's
permissions to all of the objects and folders.
5. Click OK.

16.10.2 Unarchiving a Folder Using Catalog Manager


Unarchiving is similar to pasting and therefore requires that you understand the issues
that relate to permissions and ACLS as described in Section 16.6.2.2, "Advanced
Options for Pasting Objects." Use the following procedure to unarchive a catalog
folder.
To unarchive a catalog folder:
1. In Catalog Manager, open the catalog in offline mode.
2. To unarchive a catalog folder, navigate to the location where you want to
unarchive the folder.
3. From the File menu, select Unarchive.

16-32 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Archiving and Unarchiving Using Catalog Manager

4. In the Archive File Path field, specify the path name of the catalog folder to
unarchive. Click Browse to display a dialog for selecting the path name.
5. Click OK.

Configuring and Managing the Oracle BI Presentation Catalog 16-33


Archiving and Unarchiving Using Catalog Manager

16-34 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Part VI
Part VI Advanced Configuration Settings

Part V describes configuration settings that are required for deploying a system. This
part describes advanced configuration settings that are not required but are optional
and advanced settings for fine-tuning a deployment.
This part includes the following chapters:
Chapter 17, "Configuring and Managing Analyses and Dashboards"
Chapter 18, "Configuring and Managing Agents"
Chapter 19, "Configuring Advanced Options for Mapping and Spatial
Information"
Chapter 20, "Configuring Resource Availability and URL Generation"
17
Configuring and Managing Analyses and
17

Dashboards

This chapter describes how to configure and manage analyses and dashboards and the
[18]

objects that they contain, such as views, in Oracle Business Intelligence. For
information about how content designers work with analyses and dashboards, see
Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.
End users with appropriate privileges can modify personal and shared dashboards,
including the addition of pages and content. End users cannot create analyses and
dashboards.
This chapter includes the following sections:
Managing Dashboards
Performing General Configuration Tasks for Analyses
Configuring for Displaying and Processing Data in Views
Configuring for Prompts
Manually Changing Presentation Settings
Blocking Analyses in Answers
Specifying View Defaults for Analyses and Dashboards
Configuring for Write Back in Analyses and Dashboards
Customizing the Oracle BI Web User Interface
Embedding External Content in Dashboards
Installing R and Oracle R Enterprise for External Logical SQL Functions

17.1 Managing Dashboards


Before you create shared dashboards, ensure that you have planned the Oracle BI
Presentation Catalog directory or folder structure and security strategy. In general, to
create a shared dashboard, you first create the dashboard and add content using the
Dashboard Builder. You can also assign permissions to access the dashboard. Users
who are members of multiple application roles or Catalog groups can select the
dashboard that they display by default from all of the dashboards to which they have
permissions.
The following list provides other resources with information about dashboards:
Guidelines for creating a shared dashboard, within the broader context of the
Oracle BI Presentation Catalog structure and security framework, are provided in

Configuring and Managing Analyses and Dashboards 17-1


Performing General Configuration Tasks for Analyses

"Controlling Access to Saved Customization Options in Dashboards" in Oracle


Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition.
Information about shared folder structures in the Oracle BI Presentation Catalog is
provided in Chapter 16, "Configuring and Managing the Oracle BI Presentation
Catalog."
Information about permissions is provided in Oracle Fusion Middleware Security
Guide for Oracle Business Intelligence Enterprise Edition.
Details for enabling users to act for others, which allows them to access the other
users' dashboards, is provided in "Enabling Users to Act for Others" in Oracle
Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition.

17.2 Performing General Configuration Tasks for Analyses


This section describes general tasks that you can perform to configure for the creation
of analyses. It includes the following sections:
Section 17.2.1, "Increasing Heap Size to Assist in Exports to Excel"
Section 17.2.2, "Manually Configuring for Export"
Section 17.2.3, "Supporting Nested Folders, Navigation, and Drill-Down"

17.2.1 Increasing Heap Size to Assist in Exports to Excel


Various options are available for exporting the results of analyses, for example,
exporting to Microsoft Excel. These options are described in "Exporting Results" in
Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.
While users can export directly to an Excel format, they might notice greater
performance when exporting large numbers of rows if they export first to CSV, then
import that file into Excel.
If a user exports a large data set without using the CSV format and get an
out-of-memory error, they should increase the heap size for the JavaHost service. The
default heap size is 1024MB. Depending on the available memory on the computer,
you might want to increase the heap size for the JavaHost service.
To increase the heap size for the JavaHost service to assist in exports to Excel:
1. Open the obijh.properties file for editing. You can find the file at:
ORACLE_HOME/bi/modules/oracle.bi.cam.obijh/env/obijh.properties
2. Change the existing -Xmx1024M entry (in the line starting OBIJH_ARGS=).
set the -Xmx parameter to 2048M (or higher as necessary, depending on the
available memory in the system and the size of the Excel export that you require).
3. Save and close the file.
This affects all JavaHosts.
4. If you see an error message about a SocketTimeoutException from the
com.siebel.analytics.javahost.io.ChannelWithTimeout class, then update the
SocketTimeout parameter for the JavaHost service.
Open the config.xml file for the JavaHost system component in:
BI_DOMAIN/config/fmwconfig/biconfig/OBIJH/config.xml.

17-2 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Performing General Configuration Tasks for Analyses

Locate the MessageProcessor section and the SocketTimeout parameter, which


might be commented out. Uncomment SocketTimeout if necessary and specify a
higher value. For example, specify at least 300000 milliseconds.
The config.xml file and its settings are described in Section B.2, "Using the
JavaHost Service for Oracle BI Presentation Services."
5. Save and close the file.
6. Restart Oracle Business Intelligence.

17.2.2 Manually Configuring for Export


You can configure various options that change how the results of analyses or views are
exported.
To manually edit the settings for export:
1. Open the instanceconfig.xml file for editing, located in:
BI_DOMAIN/config/fmwconfig/biconfig/OBIPS
2. Enter the following namespace declaration in the WebConfig element:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

Note that the Export element includes the required attribute xsi:type, which
specifies the type of export. Valid values are:
excel (for export to Microsoft Excel)
formattedText (for data export)
pdf (for export to PDF)
ppt (for export to Microsoft Powerpoint)
3. Locate the Download section in which you must add the elements that are
described in Table 171.
4. Include the elements and their ancestor elements as appropriate, as shown in the
following example:
Note: The default export value is UseRawValue. However, if you want to export
rounded values, you must use the value UseFormattedValue instead.
<ServerInstance>
<Download>
<Export xsi:type="excel">
<DataValue>UseRawValue</DataValue>
<RepeatRows>false</RepeatRows>
</Export>

<Export xsi:type="formattedText">
<Delimiter char=","/>
</Export>

<Export xsi:type="pdf">
<KeepRowsTogether>true</KeepRowsTogether>
<Orientation>Landscape</Orientation>
</Export>

<Export xsi:type="ppt">
<Orientation>Portrait</Orientation>
</Export>

Configuring and Managing Analyses and Dashboards 17-3


Performing General Configuration Tasks for Analyses

</Download>
</ServerInstance>

5. Save your changes and close the file.


6. Restart Oracle Business Intelligence.
Table 171 describes the elements for manually configuring for export.

Table 171 Elements for Manually Configuring for Export


Element Description Default Value
DataValue Specifies whether data values (that is, numbers UseRawValue
and dates) are exported in raw format with full
number precision and format mask or as a string
in the data format specified when exporting to
Excel.
Valid values are:
UseRawValue
UseFormattedValue
The export type is:
xsi:type="excel"
RepeatRows Specifies whether cells that span rows and cells false
that span columns are to be repeated when
exporting tables and pivot tables to Excel.
If set to true, then cells that span rows and cells
that span columns are repeated, regardless of the
Value Suppression setting in the Analysis editor.
For example, in a table that has Year and Month
values, Year is repeated for all Month values.
If set to false, then the behavior is the same as that
defined by the Value Suppression option in the
Analysis editor:
If Value Suppression is set to Suppress, then
cells that span rows and cells that span
columns are not repeated. For example, in a
table that has Year and Month values, Year is
displayed only once for Month values.
If Value Suppression is set to Repeat, then
cells that span rows and cells that span
columns are repeated. For example, in a table
that has Year and Month values, Year is
repeated for all Month values.
For more information on the Value Suppression
option, see Oracle Fusion Middleware User's Guide
for Oracle Business Intelligence Enterprise Edition.
The export type is:
xsi:type="excel"
Delimiter Specifies the column delimiter character for the ","
CSV Format option, for example, a semicolon (;),
when exporting raw data from results and views.
The export type is:
xsi:type="formattedText"

17-4 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Configuring for Displaying and Processing Data in Views

Table 171 (Cont.) Elements for Manually Configuring for Export


Element Description Default Value
KeepRowsTogether Specifies whether rows are to be kept together at false
page breaks when exporting to PDF.
If set to true, rows are kept together at page
breaks.
If set to false, rows are split across page breaks.
The export type is:
xsi:type="pdf"
Orientation Specifies the orientation (either Portrait or Landscape (for PDF
Landscape) when exporting to PDF and to exports)
Powerpoint.
Portrait (for
The export type for PDF exports is: Powerpoint
exports)
xsi:type="pdf"
The export type for Powerpoint exports is:
xsi:type="ppt"
QuoteTxtTab Adds quotes for the CSV Format option. When true
set to false, no quotes are added.
The export type is:
xsi:type="formattedText"

17.2.3 Supporting Nested Folders, Navigation, and Drill-Down


The Oracle BI Administrator can set up subject areas in ways that assist content
designers who work with analyses. Oracle Fusion Middleware Metadata Repository
Builder's Guide for Oracle Business Intelligence Enterprise Edition provides complete
information about setting up subject areas. The following list includes features of
subject areas that assist content designers:
To make selections easy for content designers to discern in the Subject Areas pane
when creating analyses, the administrator can set up the Presentation layer in the
Oracle BI Administration Tool to give the appearance of nested folders. For
example, the administrator can make the Sales Facts folder appear as a subfolder
in the Facts folder.
When content designers create analyses, they can enable users to go to related
analyses and content. If the Oracle BI Administrator sets up dimensions and
dimensional hierarchies for the subject area, then users can drill down on data
results that are presented in graphs, tables, and pivot tables to obtain more
detailed information.
There are no specific privilege settings that control access to navigation and
drill-down features, which are available to all users.
Content designers can create analyses that include columns from a primary subject
area and from one or more related subject areas.

17.3 Configuring for Displaying and Processing Data in Views


You can configure various options that change the display and processing of data in
views. See also Section 5.3.3, "Using Fusion Middleware Control to Set Configuration
Options for Data in Tables and Pivot Tables" and Section 5.3.4, "Using Fusion
Middleware Control to Set the Maximum Number of Rows Processed to Render a
Table" for related information.

Configuring and Managing Analyses and Dashboards 17-5


Configuring for Displaying and Processing Data in Views

This section contains the following topics:


Section 17.3.1, "Manually Configuring for Data in Views"
Section 17.3.2, "Manually Configuring for Graphs and Gauges"
Section 17.3.3, "Manually Changing Alternating Bar Color"
Section 17.3.4, "Manually Configuring for Interactions in Views"

17.3.1 Manually Configuring for Data in Views


You can configure various options that change the processing and display of data in
views, as described in the following sections:
Section 17.3.1.1, "Manually Configuring Cube Settings for Pivot Tables and
Graphs"
Section 17.3.1.2, "Manually Configuring Settings for Data in Views"
Section 17.3.1.3, "Manually Configuring Settings for Fetching Data for Table Views,
Pivot Table Views, and Trellis Views"

17.3.1.1 Manually Configuring Cube Settings for Pivot Tables and Graphs
You can use settings within the Cube element to affect the display and processing of
data in pivot tables and graphs. The settings also take effect for XMLA export.
To manually edit the Cube settings:
1. Open the instanceconfig.xml file for editing, located in:
BI_DOMAIN/config/fmwconfig/biconfig/OBIPS
2. Locate the Cube section, in which you must add the following element:
CubeMaxRecords Specifies the maximum number of records that are
returned by an analysis for the view to process. This roughly governs the
maximum number of cells that can be populated in a view; unpopulated cells
in a sparse view do not count. The default is 40000.
3. Include the elements and their ancestor elements as appropriate, as shown in the
following example:
<ServerInstance>
<Views>
<Cube>
<CubeMaxRecords>40000</CubeMaxRecords>
</Cube>
</Views>
</ServerInstance>

4. Save your changes and close the file.


5. Restart Oracle Business Intelligence.

17.3.1.2 Manually Configuring Settings for Data in Views


You can configure a similar group of settings that affects the display of data in table,
pivot table, graph, trellis, narrative, ticker, and treemap views. While the settings are
often the same, you must include the element within each appropriate parent element
to override the default setting that applies to that view. For example, many of the
views use the MaxVisiblePages element. You must include that element within each of

17-6 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Configuring for Displaying and Processing Data in Views

the Table, Pivot, Trellis, Charts, and Treemap parent elements, to override the default
value of that setting for each of those view types.
To manually edit the settings that change the display of data in views:
1. Open the instanceconfig.xml file for editing, located in:
BI_DOMAIN/config/fmwconfig/biconfig/OBIPS
2. Locate the Table, Pivot, Trellis, Charts, Narrative, Ticker, and Treemap parent
sections, in which you must add the elements that are described in Table 172.
3. Include the elements and their ancestor elements as appropriate, as shown in the
following example:
<ServerInstance>
<Views>
<Table>
<MaxCells>10000</MaxCells>
<MaxPagesToRollOutInDelivery>1000</MaxPagesToRollOutInDelivery>
<MaxVisiblePages>1000</MaxVisiblePages>
<MaxVisibleRows>500</MaxVisibleRows>
<MaxVisibleSections>25</MaxVisibleSections>
<DefaultRowsDisplayed>30</DefaultRowsDisplayed>
<DefaultRowsDisplayedInDelivery>250</DefaultRowsDisplayedInDelivery>
<DefaultRowsDisplayedInDownload>65000</DefaultRowsDisplayedInDownload>
<DefaultRowsDisplayedInDownloadCSV>65000</DefaultRowsDisplayedInDownlo
adCSV>
</Table>
<Pivot>
<MaxPagesToRollOutInDelivery>1000</MaxPagesToRollOutInDelivery>
<MaxVisibleColumns>300</MaxVisibleColumns>
<MaxVisiblePages>1000</MaxVisiblePages>
<MaxVisibleRows>500</MaxVisibleRows>
<MaxVisibleSections>25</MaxVisibleSections>
<Defaul