Administrator`s Guide for Oracle Business Intelligence Publisher

Administrator`s Guide for Oracle Business Intelligence Publisher
Oracle® Fusion Middleware
Administrator's Guide for Oracle Business
Intelligence Publisher
12c (12.2.1.3.0)
E80600-02
September 2017
Oracle Fusion Middleware Administrator's Guide for Oracle Business Intelligence Publisher, 12c (12.2.1.3.0)
E80600-02
Copyright © 2015, 2017, Oracle and/or its affiliates. All rights reserved.
Primary Author: Hemala Vivek
Contributing Authors: Suzanne Gill, Leslie Studdard, Reena Titus
Contributors: Oracle Business Intelligence Publisher product management, development, 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 agencyspecific 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
Audience
xiv
Documentation Accessibility
xiv
Related Documentation and Other Resources
xiv
New Features for Administrators
1
New Features and Changes for Oracle BI Publisher 12c (12.2.1.3.0)
xvi
New Features and Changes for Oracle BI Publisher 12c (12.2.1.2.0)
xvi
New Features and Changes for Oracle BI Publisher 12c (12.2.1.1.0)
xvii
Introduction to Oracle BI Publisher Administration
Introduction
1-1
Configurations Performed by the BI Platform Installer
1-2
Flow of Tasks for First Time Setup of BI Publisher
1-2
Starting and Stopping BI Publisher
1-3
Using Oracle WebLogic Server Administration Console
2
1-4
About the Administration Page
1-5
About Integration with Oracle Business Intelligence Enterprise Edition
1-5
About the Security Model Options
1-5
About the Data Source Connections
1-6
About Report Delivery Destinations
1-6
About Setting Runtime Configuration Properties
1-7
About the Server Configuration Settings
1-7
Configuring Oracle Fusion Middleware Security Model
Understanding the Security Model
2-1
Key Security Elements
2-2
Permission Grants and Inheritance
2-3
Default Security Configuration
2-5
Default Users and Groups
2-6
iii
Default Application Roles and Permissions
Granting the BIServiceAdministrator Role Catalog Permissions
Managing Authentication
Accessing Oracle WebLogic Server Administration Console
Managing Users and Groups Using the Default Authentication Provider
Managing Authorization
2-8
2-9
2-9
2-11
2-14
Accessing Oracle Enterprise Manager Fusion Middleware Control
2-15
Managing the Policy Store Using Fusion Middleware Control
2-16
Modifying Application Roles Using Fusion Middleware Control
2-16
Modifying Membership in an Application Role
2-16
Managing Credentials
2-17
Managing BI System User Credentials
2-18
Customizing the Default Security Configuration
2-18
Configuring a New Authentication Provider
2-18
Configuring a New Policy Store and Credential Store Provider
2-19
Reassociating the Policy Store and Credential Store
Customizing the Policy Store
3
2-7
2-19
2-19
Creating Application Roles Using Fusion Middleware Control
2-20
Creating Application Policies Using Fusion Middleware Control
2-22
Changing Permission Grants for an Application Policy
2-24
Alternative Security Options
About Alternative Security Options
3-1
Authentication and Authorization Options
3-2
Understanding BI Publisher Users, Roles, and Permissions
3-2
Options for Configuring Users and Roles
3-3
About Privileges to Use Functionality
3-3
About Catalog Permissions
3-4
How Functional Privileges and Permissions Work Together
3-4
A Role Must Be Assigned Catalog Permissions
3-5
A Role Can Be Granted Catalog Permissions Only
3-5
Inherited Permissions
3-5
About Access to Data Sources
3-5
Configuring Users, Roles, and Data Access
3-5
Creating Roles
3-6
Creating Users and Assigning Roles to a User
3-6
Granting Catalog Permissions
3-6
Granting Data Access
3-9
Security and Catalog Organization
Using LDAP with BI Publisher
3-9
3-12
iv
Configuring BI Publisher to Use an LDAP Provider for Authentication Only
3-12
Configuring BI Publisher to Use an LDAP Provider for Authentication and
Authorization
3-13
Setting Up Users and Roles in the LDAP Provider
3-14
Configuring the BI Publisher Server to Recognize the LDAP Server
3-15
Assigning Data Access and Catalog Permissions to Roles
3-17
Disabling Users Without BI Publisher-Specific Roles from Logging In
Integrating with Microsoft Active Directory
3-18
Configuring BI Publisher
3-19
Logging In to BI Publisher Using the Active Directory Credentials
3-20
Assigning Data Access and Catalog Permissions to Roles
3-20
3-21
How BI Publisher Operates with SSO Authentication
3-21
Tasks for Setting Up SSO Authentication with BI Publisher
3-22
Configuring SSO in an Oracle Access Manager Environment
3-22
Configuring a New Authenticator for Oracle WebLogic Server
3-23
Configuring OAM as a New Identity Asserter for Oracle WebLogic Server
3-25
Configuring BI Publisher for Oracle Fusion Middleware Security
3-26
Setting Up Oracle Single Sign-On
Setup Procedure
5
3-18
Configuring the Active Directory
Configuring BI Publisher with Single Sign-on (SSO)
4
3-18
3-26
3-26
Other Security Topics
Enabling a Local Superuser
4-1
Enabling a Guest User
4-2
Configuring BI Publisher for Secure Socket Layer (SSL) Communication
4-3
Importing Certificates for Web Services Protected by SSL
4-3
Adding the Virtualize Property to the Identity Store Configuration
4-4
Updating the JDBC Connection String to the Oracle BI EE Data Source
4-5
Updating the JMS Configuration
4-5
Configuring the Delivery Manager
4-6
Enabling Secure Cookies
4-6
Configuring Proxy Settings
4-7
Restricting Embedding of BI Publisher in iframes
4-8
Integrating with Other Oracle Security Models
About Integrating with Other Oracle Security Models
5-1
Before You Begin: Create a Local Superuser
5-1
Integrating with Oracle BI Server Security
5-2
Configuring BI Publisher for Oracle BI Server Security
5-2
v
Adding Data Sources to BI Server Roles
Integrating with Oracle E-Business Suite
5-4
Configuring BI Publisher to Use E-Business Suite Security
5-5
Adding Data Sources to the E-Business Suite Roles
5-6
Granting Catalog Permissions to the E-Business Suite Roles
5-6
5-7
Defining the BI Publisher Functional Roles in the Oracle Database
5-7
Adding Data Sources to Roles
5-8
Granting Catalog Permissions to Roles
5-8
Integrating with Oracle Siebel CRM Security
Setting Up BI Publisher Roles as Siebel CRM Responsibilities
5-9
5-9
Configuring BI Publisher to Use Siebel Security
5-10
Adding Data Sources to Roles
5-10
Granting Catalog Permissions to Roles
5-10
Implementing a Digital Signature
Introduction
6-1
Prerequisites and Limitations
6-1
Obtaining Digital Certificates
6-2
Creating PFX Files
6-2
Implementing a Digital Signature
6-3
Registering Your Digital Signature ID and Assigning Authorized Roles
6-3
Specifying the Signature Display Field or Location
6-4
Specifying a Template Field in a PDF Template for the Digital Signature
6-4
Specifying the Location for the Digital Signature in the Report Properties
6-5
Running and Signing Reports with a Digital Signature
7
5-3
Features of the Integration with E-Business Suite Security
Integrating with Oracle Database Security
6
5-3
6-6
Configuring the Scheduler
Understanding the BI Publisher Scheduler
7-1
Architecture
7-1
About Clustering
7-3
How Failover Works
7-4
Set Up Considerations
7-4
Table Space Requirements
7-4
Choosing JNDI or JDBC Connection
7-5
Supported JMS Providers
7-5
About the Scheduler Configuration
7-5
Configuring the Shared Directory
7-6
vi
Configuring Processors and Processor Threads
7-6
Adding Managed Servers
7-7
Adding a Managed Server
7-7
Configuring the Processors in BI Publisher
7-8
Setting Job Priority
Scheduler Diagnostics
Resolving Quartz Configuration Errors
8
7-10
7-13
Configuring System Maintenance Properties
Navigating to the System Maintenance Properties
8-1
Configuring the Catalog
8-2
Configuring the BI Search Fields
8-2
Setting General Properties
8-3
System Temporary Directory
8-3
About Temporary Files
8-3
Setting the System Temporary Directory
8-4
Sizing the System Temporary Directory
8-5
Report Scalable Threshold
9
7-9
8-5
Setting Server Caching Specifications
8-5
Setting Retry Properties for Database Failover
8-6
Enabling Monitor and Audit
8-6
Setting Report Viewer Properties
8-6
Clearing Report Objects from the Server Cache
8-6
Purging Job Diagnostics Log
8-7
Setting Up Data Sources
Overview of Setting Up Data Sources
9-1
About Private Data Source Connections
9-1
Granting Access to Data Sources Using the Security Region
9-3
About Proxy Authentication
9-3
Choosing JDBC or JNDI Connection Type
9-4
About Backup Databases
9-4
About Pre Process Functions and Post Process Functions
9-4
Setting Up a JDBC Connection to the Data Source
9-5
Setting Up a Database Connection Using a JNDI Connection Pool
9-9
Setting Up a Connection to an LDAP Server Data Source
9-9
Setting Up a Connection to an OLAP Data Source
9-10
Setting Up a Connection to a File Data Source
9-11
Setting Up a Connection to a Web Service
9-11
vii
10
Adding a Simple Web Service
9-12
Adding a Complex Web Service
9-13
Setting Up a Connection to a HTTP XML Feed
9-14
Setting Up a Connection to a Content Server
9-16
Viewing or Updating a Data Source
9-16
Setting Up Delivery Destinations
Configuring Delivery Options
10-1
Adding a Printer
10-2
Setting Up a Printer
Adding a Fax Server
10-5
Adding an E-Mail Server
10-6
Adding a WebDAV Server
10-6
Adding an HTTP Server
10-7
Adding an FTP Server
10-7
SSH Options for SFTP
11
10-3
10-9
Adding a Content Server
10-10
Adding a Common UNIX Printing System (CUPS) Server
10-12
Adding a Cloud Server
10-12
Defining Runtime Configurations
Setting Runtime Properties
11-1
PDF Output Properties
11-1
PDF Digital Signature Properties
11-5
PDF/A Output Properties
11-7
PDF/X Output Properties
11-8
DOCX Output Properties
11-9
RTF Output Properties
11-10
HTML Output Properties
11-10
FO Processing Properties
11-11
RTF Template Properties
11-14
PDF Template Properties
11-15
Flash Template Properties
11-16
CSV Output Properties
11-17
Excel 2007 Output Properties
11-17
All Outputs Properties
11-18
Memory Guard & Data Model Properties
11-19
Defining Font Mappings
11-19
Making Fonts Available to BI Publisher
11-19
viii
Setting Font Mapping at the Site Level or Report Level
11-19
Creating a Font Mapping
11-19
BI Publisher Predefined Fonts
11-20
Managing Custom Fonts
Defining Currency Formats
Understanding Currency Formats
12
11-22
11-22
Diagnostics and Performance Monitoring
Diagnosing and Resolving Issues in Oracle BI Publisher
12-1
About Diagnostic Log Files
12-2
About Log File Message Categories and Levels
12-2
About Log File Formats
12-2
About Log File Rotation
12-3
Configuring Log Files
12-3
Setting the Log Level
12-3
Configuring Other Log File Options
12-3
Enabling Scheduler Job Diagnostics
12-4
Viewing Log Messages
12-5
Viewing Messages by Reading the Log File
12-5
About Performance Monitoring and User Auditing
12-6
Enabling Monitoring and Auditing
12-6
Enabling Monitor and Audit on the Server Configuration Page
12-6
Configuring the Audit Policy Settings
12-6
Restarting WebLogic Server
12-8
Viewing the Audit Log
12-8
Using BI Publisher to Create Audit Reports
12-8
Registering the Data Source in BI Publisher
12-9
Creating a Data Model
12-9
Creating the Report
13
11-22
12-10
Viewing Performance Statistics in DMS Spy
12-10
Viewing Performance Statistics in the MBean Browser
12-11
Adding Translations for the BI Publisher Catalog and Reports
Introduction
Limitations of Catalog Translation
13-1
13-1
Exporting and Importing a Catalog Translation File
13-2
Template Translation
13-2
Generating the XLIFF File from the Layout Properties Page
13-3
Translating the XLIFF File
13-4
ix
Uploading the Translated XLIFF File to BI Publisher
Using the Localized Template Option
14
13-4
Designing the Localized Template File
13-5
Uploading the Localized Template to BI Publisher
13-5
Moving Catalog Objects Between Environments
Overview
14-1
When to Use the Catalog Utility
14-1
Other Options for Moving Catalog Objects
14-2
What Files Are Moved
14-2
Maintaining Identical Folder Names and Structure Across Environments
14-3
Preparing to Use the BI Publisher Catalog Utility
Configuring the Environment
14-4
14-4
Exporting BI Publisher Reporting Objects
14-4
Example Export Command Lines
14-5
Exporting a Single Report in Archive Format
14-6
Exporting a Single Report with Files Extracted
14-6
Exporting a Set of Reports to a Specified Folder
14-6
Importing BI Publisher Reporting Objects
14-6
Example Import Command Lines
14-7
Importing a Report to an Original Location
14-7
Importing a Report to a New Location
14-7
Importing a Zipped Report
14-7
Importing a set of BI Publisher Reporting Objects Under a Specified Folder
14-7
Generating Translation Files and Checking for Translatability
15
13-4
14-7
Generating a Translation File for a Report Definition File (.xdo)
14-8
Generating a Translation File for an RTF Template
14-8
Customizing the BI Publisher User Interface
What are Skins and Styles?
15-1
About Style Customizations
15-1
Modifying the User Interface Styles for BI Publisher
15-2
Customizing the Style
15-2
Customizing the Style for BI Publisher Standalone
15-2
Customizing the Style for BI Publisher Integrated with the Oracle BI Enterprise
Edition
15-4
Fallback Mechanism for Custom Styles
15-5
Custom Style Sheets
15-5
Images
15-5
x
A
Scheduler Configuration Reference
Introduction
A-1
Configuring BI Publisher for ActiveMQ
A-1
Installing ActiveMQ
A-1
Registering ActiveMQ as a JNDI Service
A-1
Updating the BI Publisher Scheduler Configuration Page
A-2
Manually Configuring the Quartz Scheduler
B
C
A-2
Recommendations for Using DataDirect Connect or Native Database Drivers
A-2
Setting Up a User on Your Scheduler Database
A-3
Connecting to Your Scheduler Database and Installing the Schema
A-3
Connecting to Oracle Databases
A-4
Connecting to IBM DB2 Databases
A-5
Connecting to Microsoft SQL Server Databases
A-5
Connecting to Sybase Adaptive Server Enterprise Databases
A-6
Integration Reference for Oracle BI Enterprise Edition
About Integration
B-1
Prerequisites
B-1
Configuring Integration with Oracle BI Presentation Services
B-1
Setting Up a JDBC Connection to the Oracle BI Server
B-2
Configuration File Reference
BI Publisher Configuration Files
C-1
Setting Properties in the Runtime Configuration File
C-1
File Name and Location
C-1
Namespace
C-1
Configuration File Example
C-2
Understanding the Element Specifications
C-2
Structure of the Root Element
C-3
Attributes of Root Element
C-3
Description of Root Element
C-3
Properties and Property Elements
<properties> Element
Description of <properties> Element
<property> Element
C-3
C-3
C-3
C-4
Attribute of <property> Element
C-4
Description of <property> Element
C-4
Font Definitions
<fonts> Element
C-4
C-4
xi
Attribute of <fonts> Element
C-5
Description of <fonts> Element
C-5
<font> Element
Attributes of <font> Element
C-5
Description of <font> Element
C-5
<font-substitute> Element
C-6
Description of <font-substitute> Element
C-6
C-6
Description of <type1> Element
C-6
Included Barcode Fonts
C-6
C-9
Audit Reference for Oracle Business Intelligence Publisher
About Custom and Standard Audit Reports
D-1
Audit Events in Oracle Business Intelligence Publisher
D-1
Enabling Memory Guard Features
What Are Memory Guard Features?
E-1
Key Features
E-1
Restricting Maximum Data Sizes for Report Processing
E-2
Configuring Free Memory Threshold
E-2
Setting Data Engine Properties
E-4
Configuring Memory Guard and Data Model Properties
Using runtimepropertiesconfig.sh Command Line Utility
F
C-6
Attribute of <type1> Element
Predefined Fonts
E
C-6
Attributes of <font-substitute> Element
<type1> element
D
C-5
E-5
E-8
Configuring a Maximum Threads Constraint to Avoid Out of Memory Errors
E-9
Creating the Maximum Threads Constraint in Oracle WebLogic Server
E-10
Creating the Work Manager (XdoWorkManager)
E-13
Redeploying the xmlpserver.ear File
E-16
Updating the BI Publisher Context Root
Updating the BI Publisher URL Context Root
F-1
Example
F-1
Updating the xmlpserver META-INF/application.xml File
F-2
Updating the xmlpserver WAR/WEB-INF/web.xml File
F-2
Updating the xmlpserver WAR/WEB-INF/weblogic.xml File
F-2
Updating the xmlp-server-config.xml File
F-3
Updating the analytics META-INF/application.xml File
F-3
xii
Updating the instanceconfig.xml File
F-3
Updating the bipublisher and analytics Applications in WebLogic Server
F-4
xiii
Preface
Preface
Welcome to Release 12c (12.2.1.3.0) of the Administrator's Guide for Oracle Business
Intelligence Publisher.
Audience
This document is intended for system administrators who are responsible for
managing Oracle Business Intelligence Publisher processes, logging, caching,
monitoring, data source connections, delivery servers, security, 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.
Related Documentation and Other Resources
If you want to know more about BI products and services, Oracle provides a wide
range of learning materials .
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 1338762.1) on My
Oracle Support at https://support.oracle.com.
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).
xiv
Preface
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/fusionrequirements-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/fusioncertification-100350.html
xv
New Features for Administrators
New Features for Administrators
This preface describes changes to the Oracle BI Publisher Administrator.
New Features and Changes for Oracle BI Publisher 12c
(12.2.1.3.0)
This section includes new features and changes for Oracle BI Publisher 12c
(12.2.1.3.0) release.
Job Priority and Recovery
You can set the priority of each report to avoid delays of critical jobs and recover
interrupted jobs to increase the success rate of running jobs. See Setting Job Priority.
Restricting Embedding of BI Publisher in iframes
You can prevent embedding of BI Publisher in iframes. See Restricting Embedding of
BI Publisher in iframes.
New Features and Changes for Oracle BI Publisher 12c
(12.2.1.2.0)
This section includes new features and changes for Oracle BI Publisher 12c
(12.2.1.2.0).
Memory Guard Properties
•
Memory guard properties are the same as in 12.2.1.0.
•
New runtimepropertiesconfig.sh command line utility is available for setting the
memory guard properties.
For a description of memory guard properties, see Enabling Memory Guard Features.
xvi
New Features for Administrators
New Features and Changes for Oracle BI Publisher 12c
(12.2.1.1.0)
This section includes new features and changes for Oracle BI Publisher 12c
(12.2.1.1.0).
Content Server as a Data Source
Content Server data source enables you to retrieve data from a text file stored in
Oracle WebContent Center (formerly known as Universal Content Management)
server and display the data in a report output. See Setting Up a Connection to a
Content Server.
Self-Service Feature to Upload and Manage Fonts
BI Publisher includes a standard set of fonts. You can use the standard fonts and you
can upload additional fonts for use in reports. See Managing Custom Fonts.
Dynamic Data Size Limit to Optimize Memory Guard for Different Outputs
Memory guard configuration has been enhanced to make it dynamic. You can now
define separate memory guard thresholds for each template type and configure its
memory estimate formula, which can adjust dynamically based on the report data size.
See What Are Memory Guard Features?
xvii
1
Introduction to Oracle BI Publisher
Administration
This chapter describes tasks required to administer BI Publisher.
It includes the following topics:
•
Introduction
•
Configurations Performed by the BI Platform Installer
•
Flow of Tasks for First Time Setup of BI Publisher
•
Starting and Stopping BI Publisher
•
About the Administration Page
•
About Integration with Oracle Business Intelligence Enterprise Edition
•
About the Security Model Options
•
About the Data Source Connections
•
About Report Delivery Destinations
•
About Setting Runtime Configuration Properties
•
About the Server Configuration Settings
Introduction
Oracle BI Publisher is an enterprise reporting solution for authoring, managing, and
delivering all your highly formatted documents, such as operational reports, electronic
funds transfer documents, government PDF forms, shipping labels, checks, sales and
marketing letters, and much more.
Administering BI Publisher requires setting up and maintaining the following system
components:
•
BI Publisher security
•
Data source connections
•
Report delivery destinations
•
BI Publisher Scheduler configurations
•
Runtime configuration settings
•
Server configuration settings
See the guides that are outlined in the table below for more information about using
the product for other business roles.
Role
Sample Tasks
Guide
Data Model developer
Fetching and structuring the Data Modeling Guide for Oracle
data to use in reports
Business Intelligence Publisher
1-1
Chapter 1
Configurations Performed by the BI Platform Installer
Role
Sample Tasks
Guide
Application developer or
integrator
Integrating BI Publisher into Developer's Guide for Oracle
existing applications using
Business Intelligence Publisher
the application programming
interfaces
Report consumer
Viewing reports
Scheduling report jobs
User's Guide for Oracle Business
Intelligence Publisher
Managing report jobs
Report designer
Creating report definitions
Designing layouts
Report Designer's Guide for Oracle
Business Intelligence Publisher
Configurations Performed by the BI Platform Installer
After installation is complete, the BI Platform Installer performs certain configurations.
Post-installation configurations include:
•
The security model is configured to use Oracle Fusion Middleware Security
•
The scheduler is configured to use Oracle WebLogic JMS. The schema tables are
installed and configured in the database
•
The BI Publisher catalog and repository are configured to ${xdo.server.config.dir}/
repository
Flow of Tasks for First Time Setup of BI Publisher
If you are setting up BI Publisher for the first time, then consult the following table for
the recommended flow of tasks to get the system up and running.
Task
Where to Get Information
Define a Local Superuser Set up this
Enabling a Local Superuser
Superuser to ensure access to all
administrative functions in case of problems
with the current security setup.
Set up the chosen security model and test
Configuring Oracle Fusion Middleware Security
Model
Alternative Security Options
Integrating with Other Oracle Security Models
Set up the data sources and test
Setting Up Data Sources
Set up the delivery servers and test
Setting Up Delivery Destinations
Configure server properties
Configuring System Maintenance Properties
Configure system runtime properties
Defining Runtime Configurations
1-2
Chapter 1
Starting and Stopping BI Publisher
Starting and Stopping BI Publisher
Use the Oracle WebLogic Server Administration Console to centrally manage Oracle
Business Intelligence Publisher.
For detailed information about Oracle WebLogic Server, see Oracle WebLogic Server
Administration Console Online Help.
Display Oracle WebLogic Server Administration Console, using one of the following
methods:
•
Using the Start menu in Windows
•
Clicking a link on the Overview page 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.
To display Oracle WebLogic Server Administration Console:
1.
If the Administration Server for WebLogic Server is not running, start it.
2.
Display the Oracle WebLogic Server Administration Console using one of the
following methods:
Using the Windows Start menu:
a.
From the Start menu, select All Programs, Oracle WebLogic, User
Projects, bifoundation_domain, and Admin Server Console.
The Oracle WebLogic Server Administration Console login page is displayed.
Clicking a link on the Overview page in Fusion Middleware Control:
a.
Display Oracle Fusion Middleware Control.
b.
Expand the WebLogic Domain node and select the bifoundation_domain.
c.
Click the Oracle WebLogic Server Administration Console link in the Summary
region.
The Oracle WebLogic Server Administration Console login page is displayed.
Using a URL in a Web browser window:
a.
Enter the following URL into the browser:
http://<host>:<port>/console/.
For example, http://mycomputer:7001/console/
where host 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 7001 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 Socket
Layer (SSL), then you must add the letter 's' after http as follows:
https://<host>:7001/console/
1-3
Chapter 1
Starting and Stopping BI Publisher
Using Oracle WebLogic Server Administration Console
Use the Oracle WebLogic Server Administration Console to start and stop BI
Publisher.
1.
Start the Oracle WebLogic Server Administration Console.
2.
Under the Domain Structure, click Deployments.
3.
Click Control.
4.
In the Deployments table, select the bipublisher application.
5.
Click the appropriate action, as shown below.
When you Start an application, pick one of the following options:
•
Servicing all requests: Specifies that WebLogic Server make the application
immediately available to all clients.
•
Servicing only administration requests: Specifies that WebLogic Server make
the application available in Administration Mode only.
When you Stop an application, pick one of the following options:
•
When work completes: Specifies that WebLogic Server wait for the application to
finish its work and for all currently connected users to disconnect.
•
Force stop now: Specifies that WebLogic Server stop the application
immediately, regardless of the work that is being performed and the users that are
connected.
•
Stop, but continue servicing administration requests: Specifies that WebLogic
Server stop the application once all its work has finished, but to then put the
application in Administration Mode so it can be accessed for administrative
purposes.
1-4
Chapter 1
About the Administration Page
About the Administration Page
Many of the tasks described in the Administration section of this guide are performed
from the BI Publisher Administration page.
You must be granted Administrator privileges to access the Administration page. The
Administration page is accessed from the Administration link in the global header.
About Integration with Oracle Business Intelligence
Enterprise Edition
If you installed Oracle BI Publisher with the Oracle Business Intelligence Enterprise
Edition, then you must perform the Administration tasks in the BI Publisher
Administration page.
Administration tasks are described in the following table. Navigate to the BI Publisher
Administration page as follows:
In the global header, click Administration, on the Administration page, click Manage
BI Publisher.
Task
Where to Get Information
Set up data source connections for reporting
Setting Up Data Sources
Grant access to data sources for user roles defined Granting Data Access
in Oracle Business Intelligence
Configure the connections to delivery servers (for
Setting Up Delivery Destinations
example, printers, e-mail servers, FTP servers, and
so on)
Configure the scheduler processors
Configuring the Scheduler
Configure system runtime properties such as PDF
security properties, properties specific to each
output format, template type properties, font
mappings, and currency formats.
Setting Runtime Properties
Configure server properties such as caching
specifications, database failover properties, and
database fetch size.
Configuring System Maintenance
Properties
About the Security Model Options
BI Publisher offers a variety of security options.
•
Oracle Fusion Middleware Security
After installation, BI Publisher is configured to use Oracle Fusion Middleware
Security. See Configuring Oracle Fusion Middleware Security Model. If you prefer
to use another security model, then choose from the alternative options.
•
BI Publisher Security
Use BI Publisher's Users and Roles paradigm to control access to reports and
data sources. See Alternative Security Options.
1-5
Chapter 1
About the Data Source Connections
•
Integration with an LDAP server
Set up the BI Publisher roles in your LDAP server then configure BI Publisher to
integrate with it. See Alternative Security Options.
•
Oracle E-Business Suite
Upload a DBC file to recognize your Oracle E-Business Suite users. See
Integrating with Other Oracle Security Models
•
Oracle BI Server
You can still leverage the 10g legacy BI Server authentication method if you
choose not to upgrade to Oracle Fusion Middleware Security. See Integrating with
Other Oracle Security Models.
•
Oracle Database
Set up the BI Publisher roles in your Oracle Database and then configure BI
Publisher to integrate with it. See Integrating with Other Oracle Security Models.
•
Oracle Siebel CRM Security Model
See Integrating with Other Oracle Security Models.
About the Data Source Connections
BI Publisher reports rely on XML data. BI Publisher supports retrieving data from a
variety of data sources.
The following data sources must be first set up in BI Publisher through the
Administration page:
•
Database connections
BI Publisher supports direct JDBC connections and connections through a JNDI
pool (recommended)
•
LDAP connections
•
OLAP connections
•
File directory connections - you can use existing XML files, Microsoft Excel files, or
CSV files stored in a directory that BI Publisher can access
•
Web Service connections
•
HTTP XML connections
For more information on setting up these data source connections, see Setting Up
Data Sources.
If you have integrated your system with Oracle Business Intelligence you can also take
advantage of the following data sources:
•
Oracle BI Analysis
•
Oracle BI Server subject area
You can also upload some file types stored locally.
About Report Delivery Destinations
The BI Publisher delivery manager supports multiple delivery channels.
1-6
Chapter 1
About Setting Runtime Configuration Properties
Supported delivery channels include:
•
Printer
•
Fax
•
E-mail
•
HTTP notification
•
FTP
•
Web Folder (or WebDAV)
•
Content Server
•
Document Cloud Services
For more information on setting up the delivery options, see Setting Up Delivery
Destinations.
About Setting Runtime Configuration Properties
Use the Runtime Configuration page to enable configuration settings for your system.
The properties include settings that do the following:
•
Control the processing for different output types
•
Enable digital signature
•
Tune for scalability and performance
•
Define font mappings
For more information on setting configuration properties and font mappings, see
Setting Runtime Properties.
About the Server Configuration Settings
BI Publisher administration also includes a set of system maintenance settings and
tasks.
Settings and tasks include:
•
Configuring the catalog
•
Setting caching properties
•
Setting retry properties for failover
•
Enabling Auditing and Monitoring
For more information on these tasks and settings, see Configuring System
Maintenance Properties.
1-7
2
Configuring Oracle Fusion Middleware
Security Model
This chapter describes how to configure Oracle Fusion Middleware security model for
BI Publisher.
It includes the following topics:
•
Understanding the Security Model
•
Key Security Elements
•
Permission Grants and Inheritance
•
Default Security Configuration
•
Managing Authentication
•
Managing Authorization
•
Managing Credentials
•
Customizing the Default Security Configuration
Understanding the Security Model
The Oracle Fusion Middleware security model is built upon the Oracle Fusion
Middleware platform, which incorporates the Java security model.
The Java model is a role-based, declarative model that employs container-managed
security where resources are protected by roles that are assigned to users. However,
extensive knowledge of the Java-based architecture is unnecessary when using the
Oracle Fusion Middleware Security model. When using this security model, BI
Publisher can furnish uniform security and identity management across the enterprise.
After installation BI Publisher is automatically installed into an Oracle WebLogic Server
domain, which is a logically related group of WebLogic Server resources that are
managed as a unit. After a Simple installation type the WebLogic Server domain that is
created is named bifoundation_domain. This name might vary depending upon the
installation type performed. One instance of WebLogic Server in each domain is
configured as an Administration Server. The Administration Server provides a central
point for managing a WebLogic Server domain. The Administration Server hosts the
Administration Console, which is a Web application accessible from any supported
Web browser with network access to the Administration Server. BI Publisher is part of
the active security realm configured for the Oracle WebLogic Server domain into which
it is installed.
See Securing Applications with Oracle Platform Security Services. For more
information about managing the Oracle WebLogic Server domain and security realm,
see Understanding Security for Oracle WebLogic Server and Administering Security
for Oracle WebLogic Server.
2-1
Chapter 2
Key Security Elements
Key Security Elements
The Oracle Fusion Middleware security model depends upon key elements to provide
uniform security and identity management across the enterprise
These key elements include:
•
Application policy
BI Publisher permissions are granted to members of its application roles. In the
default security configuration, each application role conveys a predefined set of
permissions. Permission grants are defined and managed in an application
policy. After an application role is associated with an application policy, that role
becomes a Grantee of the policy. An application policy is specific to a particular
application.
•
Application role
After permission grants are defined in an application policy, an application role can
be mapped to that policy, and the application role then becomes the mechanism to
convey the permissions. In this manner an application role becomes the
container that grants permissions to its members. The permissions become
associated with the application role through the relationship between policy and
role. After groups are mapped to an application role, the corresponding
permissions are granted to all members equally. Membership is defined in the
application role definition. Application roles are assigned in accordance with
specific conditions and are granted dynamically based on the conditions present at
the time authentication occurs. More than one user or group can be members of
the same application role.
•
Authentication provider
An authentication provider is used to access user and group information and is
responsible for authenticating users. The default authentication provider that BI
Publisher uses during a Simple or Enterprise installation is named
DefaultAuthenticator. This is the same default authenticator used by a basic
Oracle WebLogic Server installation. An Oracle WebLogic Server authentication
provider enables you to manage users and groups in one place.
An identity store contains user name, password, and group membership
information. An authentication provider accesses the data in the identity store and
authenticates against it. For example, when a user name and password
combination is entered at log in, the authentication provider searches the identity
store to verify the credentials provided. The BI Publisher default authentication
provider authenticates against Oracle WebLogic Server embedded directory
server.
•
Users and groups
A user is an entity that can be authenticated. A user can be a person, such as an
application user, or a software entity, such as a client application. Every user is
given a unique identifier.
Groups are organized collections of users that have something in common. Users
should be organized into groups with similar access needs to facilitate efficient
security management.
•
Security realm
2-2
Chapter 2
Permission Grants and Inheritance
During installation an Oracle WebLogic Server domain is created and BI Publisher
is installed into that domain. BI Publisher security is managed within the security
realm for this Oracle WebLogic Server domain. A security realm acts as a scoping
mechanism. Each security realm consists of a set of configured security providers,
users, groups, security roles, and security policies. Only one security realm can be
active for the domain. BI Publisher authentication is performed by the
authentication provider configured for the default security realm for the WebLogic
Server domain in which it is installed. Oracle WebLogic Server Administration
Console is the administration tool used for managing an Oracle WebLogic Server
domain.
Permission Grants and Inheritance
BI Publisher provides application-specific permissions for accessing different features.
BI Publisher permissions are typically granted by becoming a member in an
application role. Permissions can be granted two ways: through membership in an
application role (direct) and through group and role hierarchies (inheritance).
Application role membership can be inherited by nature of the application role
hierarchy. In the default security configuration, each application role is preconfigured
to grant a predefined set of permissions. Groups are mapped to an application role.
The mapping of a group to a role conveys the role's permissions to all members of the
group. In short, permissions are granted in BI Publisher by establishing the following
relationships:
•
A group defines a set of users having similar system access requirements. Users
are added as members to one or more groups according to the level of access
required.
•
Application roles are defined to represent the role a user typically performs when
using BI Publisher. The default security configuration provides the following
preconfigured application roles: BIServiceAdministrator (an administrator),
BIContentAuthor (an author of content), and BIConsumer (a consumer of content).
•
The groups of users are mapped to one or more application roles that match the
type of access required by the population.
•
Application policies are created and BI Publisher permissions are mapped that
grant a set of access rights corresponding to role type.
•
An application role is mapped to the application policy that grants the set of
permissions required by the role type (an administrator, an author, a consumer).
•
Group membership can be inherited by nature of the group hierarchy. Application
roles mapped to inherited groups are also inherited, and those permissions are
likewise conveyed to the members.
How a user's permissions are determined by the system is as follows:
1.
A user enters credentials into a Web browser at login. The user credentials are
authenticated by the authentication provider against data contained in the identity
store.
2.
After successful authentication, a Java subject and principal combination is issued,
which is populated with the user name and the user's groups.
3.
A list of the user's groups is generated and checked against the application roles.
A list is created of the application roles that are mapped to each of the user's
groups.
2-3
Chapter 2
Permission Grants and Inheritance
4.
A user's permission grants are determined from knowing which application roles
the user is a member of. The list of groups is generated only to determine what
roles a user has, and is not used for any other purpose.
A user can also be granted permissions if they inherit other application roles. Members
of application roles can include other groups and application roles. The result is a
hierarchical role structure where permissions can be inherited in addition to being
explicitly granted. This hierarchy provides that a group is granted the permissions of
the application role for which it is a member, and the permissions granted by all roles
descended from that role.
For example, the default security configuration includes several predefined groups and
application roles. The default BIServiceAdministrator application role includes the
BIAdministrators group, the BIContentAuthor application role includes the BIAuthors
group, and the BIConsumer application role includes the BIConsumers group. The
default BIServiceAdministrator application role is a member of the BIContentAuthor
application role, and the BIContentAuthor application role is a member of the
BIConsumer application role. The members of these application roles inherit
permissions as follows. Members of the BIAdministrators group are granted all the
permissions of the BIServiceAdministrator role, the BIContentAuthor role, and the
BIConsumer role. By nature of this role hierarchy, the user who is a member of a
particular group is granted permissions both explicitly and through inheritance. For
more information about the default application roles and groups, see Default
Application Roles and Permissions.
Note:
By themselves, groups and group hierarchies do not enable any privilege to
access resources controlled by an application. Privileges are conveyed by the
permission grants defined in an application policy. A user, group, or
application role becomes a Grantee of the application policy. The application
policy Grantee conveys the permissions and this is done by direct association
(user) or by becoming a member of the Grantee (group or application role).
The figure below shows these relationships between the default groups and
application roles.
2-4
Chapter 2
Default Security Configuration
The table below summarizes how permissions are granted explicitly or are inherited in
the previous example and figure.
User Name
Group Membership:
Explicit/Inherited
Application Role
Membership:
Explicit/Inherited
Permission Grants:
Explicit/Inherited
User1, User2,
User3
BIConsumers: Explicit
BIConsumer:
Explicit
Permission A: Explicit
User4, User5
BIAuthors: Explicit
BIConsumers: Inherited
BIContentAuthor:
Explicit
BIConsumer:
Inherited
Permission B: Explicit
Permission A: Inherited
User6, User7
BIAdministrators: Explicit
BIAuthors: Inherited
BIConsumers: Inherited
BIServiceAdministra Permission C: Explicit
tor: Explicit
Permission B: Inherited
BIContentAuthor:
Permission A: Inherited
Inherited
BIConsumer:
Inherited
Default Security Configuration
Access control of system resources is achieved by requiring users to authenticate at
login and by restricting users to only those resources for which they are authorized.
A default security configuration is available for immediate use after BI Publisher is
installed and is configured to use the Oracle Fusion Middleware security model. BI
Publisher is installed into the Oracle WebLogic Server domain and uses its security
realm. The default configuration includes three predefined security stores available for
managing user identities, credentials, and BI Publisher-specific permission grants.
Users can be added to predefined groups that are mapped to preconfigured
application roles. Each application role is preconfigured to grant specific BI Publisher
permissions.
The BI Publisher default security stores are configured as described in the table below
during installation.
2-5
Chapter 2
Default Security Configuration
Store Name
Purpose
Identity store
•
•
Policy store
•
•
Default Provider
Used to control
•
authentication.
Stores the users and
groups, and the
•
users group for
Oracle WebLogic
Server embedded
directory server.
Oracle WebLogic
Server embedded
directory server.
Managed with
Oracle WebLogic
Server
Administration
Console.
BI Publisher can be
configured to use
alternative
authentication
providers. For a
complete list, see
System
Requirements and
Certification.
Used to control
•
authorization.
Stores the
application role
definitions and the
mapping definitions
between groups and
application roles.
system.jazndata.xml file.
Default installation
location is
BI Publisher can be
configured to use
Oracle Internet
Directory as the
policy store provider.
•
Credential store
Options
Stores the passwords
•
and other security-related •
credentials either
supplied or systemgenerated.
MW_HOME/
user_projects
/domain/
your_domain/
config/
fmwconfig
Managed with
Oracle Enterprise
Manager Fusion
Middleware Control.
cwallet.sso file.
Managed using
Fusion Middleware
Control.
BI Publisher can be
configured to use
Oracle Internet
Directory as the
credential store
provider.
Default Users and Groups
Default user and group names can be changed to different values and new names can
be added by an administrative user using Oracle WebLogic Server Administration
Console.
The table below lists the default user names and passwords added to the BI Publisher
identity store provider after installation.
2-6
Chapter 2
Default Security Configuration
Default User Name
and Password
Purpose
Description
Name:
Is the administrative user.
This user name is entered by the
person performing the installation, it
can be any desired name, and does
not need to be named Administrator.
administrator user
Password:
user supplied
The password entered during
installation can be changed later using
the administration interface for the
identity store provider.
This single administrative user is
shared by BI Publisher and Oracle
WebLogic Server. This user is
automatically made a member of the
Oracle WebLogic Server default
Administrators group after installation.
This enables this user to perform all
Oracle WebLogic Server administration
tasks, including the ability to manage
Oracle WebLogic Server's embedded
directory server.
No default groups are created during the installation of BI Publisher.
Default Application Roles and Permissions
Permissions in BI Publisher are granted by specific roles. Permissions can also be
inherited from group and application role hierarchies.
The table below lists the BI Publisher permissions and the application role that grants
these permissions. This mapping exists in the default policy store.
The table also lists the permissions explicitly granted by membership in the
corresponding default application role. Permissions can also be inherited from group
and application role hierarchies. For more information about permission inheritance,
see Permission Grants and Inheritance.
BI Publisher
Permission
Description
Default Application Role
Granting Permission
Explicitly
oracle.bi.publisher.ad Enables the Administration link to access BIServiceAdministrator
ministerServer
the Administration page and grants
permission to set any of the system
settings.
Important: See Granting the
BIServiceAdministrator Role Catalog
Permissions for additional steps required
to grant the BIServiceAdministrator
permissions on Shared Folders.
oracle.bi.publisher.de Grants permission to create or edit data
velopDataModel
models.
BIContentAuthor
2-7
Chapter 2
Default Security Configuration
BI Publisher
Permission
Description
oracle.bi.publisher.de Grants permission to create or edit
velopReport
reports, style templates, and sub
templates. This permission also enables
connection to the BI Publisher server
from the Template Builder.
oracle.bi.publisher.ru
nReportOnline
Default Application Role
Granting Permission
Explicitly
BIContentAuthor
Grants permission to open (execute)
BIConsumer
reports and view the generated document
in the report viewer.
oracle.bi.publisher.sc Grants permission to create or edit jobs
heduleReport
and also to manage and browse jobs.
BIConsumer
oracle.bi.publisher.ac Grants permission to browse and
cessReportOutput
manage job history and output.
BIConsumer
BIConsumer
permissions granted
implicitly
The authenticated role is a member of
Authenticated Role
the BIConsumer role by default and, as
such, all authenticated role members are
granted the permissions of the
BIConsumer role implicitly.
The authenticated role is a special application role provided by the Oracle Fusion
Middleware security model and is made available to any application deploying this
security model. BI Publisher uses the authenticated application role to grant
permissions implicitly derived by the role and group hierarchy of which the
authenticated role is a member. The authenticated role is a member of the
BIConsumer role by default and, as such, all authenticated role members are granted
the permissions of the BIConsumer role implicitly. By default, every authenticated user
is automatically added to the BIConsumers group. The authenticated role is not stored
in the obi application stripe and is not searchable in the BI Publisher policy store.
However, the authenticated role is displayed in the administrative interface for the
policy store, is available in application role lists, and can be added as a member of
another application role. You can map the authenticated role to another user, group, or
application role, but you cannot remove the authenticated role itself. Removal of the
authenticated role would result in the inability to log in to the system and this right
would need to be granted explicitly.
For more information about the Oracle Fusion Middleware security model and the
authenticated role, see Securing Applications with Oracle Platform Security Services.
Granting the BIServiceAdministrator Role Catalog Permissions
The BIServiceAdministrator role is granted only Read permissions on the catalog by
default.
This means that before a BIServiceAdministrator can manage Shared Folders the
BIServiceAdministrator role must be granted Write and Delete permissions on the
Shared Folders node. See Granting Catalog Permissions for a detailed description of
granting permissions in the catalog.
2-8
Chapter 2
Managing Authentication
Managing Authentication
Authentication is the process of verifying identity by confirming the user is who he
claims to be. Oracle WebLogic Server embedded directory server is the authentication
provider for the default security configuration.
Users, groups, and passwords are managed using Oracle WebLogic Server
Administration Console. It is fine to use the default authentication provider for a
development or test environment. In a production environment, best practice is to use
a full featured authentication provider.
Note:
Refer to the system requirements and certification documentation for
information about hardware and software requirements, platforms, databases,
and other information. These documents are available on Oracle Technology
Network (OTN).
During installation an Oracle WebLogic Server domain is created. BI Publisher is
installed into that domain and uses the Oracle WebLogic Server security realm. The
security realm can have multiple authentication providers configured but only one
provider can be active at a time. The order of providers in the list determines priority.
The effect of having multiple authentication providers defined in a security realm is not
cumulative; rather, the first provider in list is the source for all user and password data
needed during authentication. This enables you to switch between authentication
providers as needed. For example, if you have separate LDAP servers for your
development and production environments, you can change which directory server is
used for authentication by re-ordering them in the Administration Console. For
information about how to configure a different authentication provider, see Configuring
a New Authentication Provider.
Detailed information about managing an authentication provider in Oracle WebLogic
Server is available in its online help. For more information, log in to Oracle WebLogic
Server Administration Console and launch Oracle WebLogic Server Administration
Console Online Help.
Accessing Oracle WebLogic Server Administration Console
Oracle WebLogic Server is automatically installed and serves as the default
administration server.
The Administration Console is browser-based and is used to manage the embedded
directory server that is configured as the default authenticator. It is launched by
entering its URL into a web browser. The default URL takes the following form:
http://hostname:port_number/console. The port number is the number of the
administration server. By default, the port number is 7001.
To launch the Oracle WebLogic Server Administration Console:
1.
Log in to Oracle WebLogic Server by entering its URL into a Web browser.
2-9
Chapter 2
Managing Authentication
For example, http://hostname:7001/console. The Administration Console
login page displays, as shown the figure below.
2.
Log in using the BI Publisher administrative user and password and click Login.
The password is the one you supplied during the installation of BI Publisher. If
these values have been changed, then use the current administrative user name
and password combination.
The Administration Console displays, as shown the figure below.
2-10
Chapter 2
Managing Authentication
Managing Users and Groups Using the Default Authentication
Provider
Managing a group is more efficient than managing a large number of users
individually. Best practice is to first organize all BI Publisher users into groups that
have similar system access requirements.
These groups can then be mapped to application roles that provide the correct level of
access. If system access requires change, then you need only modify the permissions
granted by the application roles, or create a new application role with appropriate
permissions. Once your groups are established, continue to add or remove users
directly in the identity store using its administration interface as you normally would.
To create a user in the default directory server:
1.
If needed, launch Oracle WebLogic Server Administration Console.
See Accessing Oracle WebLogic Server Administration Console.
2.
Log in as an administrative user.
3.
In the Administration Console, select Security Realms from the left pane and click
the realm you are configuring. For example, myrealm.
4.
Select Users and Groups tab (shown below), then Users. Click New.
5.
In the Create a New User page (shown below) provide the following information:
•
Name: Enter the name of the user. See online help for a list of invalid
characters.
•
(Optional) Description: Enter a description.
•
Provider: Select the authentication provider from the list that corresponds to
where the user information is contained. DefaultAuthenticator is the name for
the default authentication provider.
•
Password: Enter a password for the user that is at least 8 characters long.
2-11
Chapter 2
Managing Authentication
•
6.
Confirm Password: Re-enter the user password.
Click OK.
The user name is added to the User table.
To create a group in the default directory server:
1.
If needed, launch Oracle WebLogic Server Administration Console.
See Accessing Oracle WebLogic Server Administration Console.
2.
Log in as an administrative user.
3.
In the Administration Console, select Security Realm from the left pane and click
the realm you are configuring. For example, myrealm.
4.
Select Users and Groups tab, then Groups. Click New.
5.
In the Create a New Group page provide the following information:
6.
•
Name: Enter the name of the Group. Group names are case insensitive but
must be unique. See the online help for a list of invalid characters.
•
(Optional) Description: Enter a description.
•
Provider: Select the authentication provider from the list that corresponds to
where the group information is contained. DefaultAuthenticator is the name for
the default authentication provider.
Click OK.
The group name is added to the Group table.
To add a user to a group in the default directory server:
2-12
Chapter 2
Managing Authentication
1.
If needed, launch Oracle WebLogic Server Administration Console.
See Accessing Oracle WebLogic Server Administration Console.
2.
Log in as an administrative user.
3.
In the Administration Console, select Security Realm from the left pane and click
the realm you are configuring. For example, myrealm.
4.
Select Users and Groups tab, then Users, as shown in the figure below. Select
the user from Name.
5.
From the Settings page, select the Groups tab to display the list of available
groups.
6.
Select one or more groups from the Available list and use the shuttle controls to
move them to the Chosen list, as shown below.
2-13
Chapter 2
Managing Authorization
7.
Click Save.
The user is added to the group.
To change a user password in the default directory server:
1.
If needed, launch Oracle WebLogic Server Administration Console.
See Accessing Oracle WebLogic Server Administration Console.
2.
Log in as an administrative user.
3.
In the Administration Console, select Security Realms from the left pane and click
the realm you are configuring. For example, myrealm.
4.
Select Users and Groups tab, then Users.
5.
In the Users table select the user you want to change the password for.
The settings page for the user displays, as shown below.
6.
Select the Passwords tab and enter the password in the New Password and
Confirm Password fields.
7.
Click Save.
Managing Authorization
After a user is authenticated, further access to BI Publisher resources is controlled by
the granting of permissions, also known as authorization.
The policy store contains the system and application-specific policies and roles
required for BI Publisher. A policy store can be file-based or LDAP-based and holds
the mapping definitions between the default BI Publisher application roles,
permissions, users and groups. BI Publisher permissions are granted by mapping
users and groups from the identity store to application roles and permission grants
located in the policy store. These mapping definitions between users and groups
(identity store) and the application roles (policy store) are also kept in the policy store.
Note:
Best practice is to map groups instead of individual users to application roles.
Controlling membership in a group reduces the complexity of tracking access
rights for multiple individual users. Group membership is controlled in the
identity store.
2-14
Chapter 2
Managing Authorization
The system-jazn-data.xml file is installed and configured as the default policy store.
You can continue to use the default store and modify it as needed for your
environment, or you can migrate its data to an LDAP-based provider. Oracle Internet
Directory is the supported LDAP server in this release.
The policy store and credential store must be of the same type in your environment.
That is, both must be either file-based or LDAP-based.
Permissions must be defined in a manner that BI Publisher understands. All valid BI
Publisher permissions are premapped to application policies, which are in turn
premapped to the default application roles. You cannot create new permissions in the
policy store. However, you can customize the default application policy permission
grants and application role mappings and you can create your own.
For more information about the default BI Publisher permissions grants, see Default
Application Roles and Permissions. For more information about customizing
application roles and permission grants, see Customizing the Policy Store.
Accessing Oracle Enterprise Manager Fusion Middleware Control
Fusion Middleware Control is a Web browser-based, graphical user interface that you
can use to monitor and administer a farm.
A farm is a collection of components managed by Fusion Middleware Control. It can
contain Oracle WebLogic Server domains, one Administration Server, one or more
Managed Servers, clusters, and the Oracle Fusion Middleware components that are
installed, configured, and running in the domain. During installation an Oracle
WebLogic domain is created and BI Publisher is installed into that domain. If you
performed a Simple or Enterprise installation type, this domain is named
bifoundation_domain and is located within the WebLogic Domain in the Fusion
Middleware Control target navigation pane.
Launch Fusion Middleware Control by entering its URL into a Web browser. The URL
includes the name of the host and the administration port number assigned during the
installation. This URL takes the following form: http://
hostname:port_number/em. The default port is 7001. For more information about
using Fusion Middleware Control, see Administering Oracle Fusion Middleware.
To display the Security menu in Fusion Middleware Control:
1.
Log into Oracle Enterprise Manager Fusion Middleware Control by entering the
URL in a Web browser.
For example, http://hostname:7001/em.
2.
Enter the BI Publisher administrative user name and password and click Login.
The password is the one you supplied during the installation of BI Publisher. If
these values have been changed, then use the current administrative user name
and password combination.
3.
From the target navigation pane, open WebLogic Domain to display
bifoundation_domain. Display the Security menu by selecting one of the
following methods:
•
Right-click bifoundation_domain to display the Security menu. Select
Security to display a submenu.
•
From the content pane, display the WebLogic Domain menu and select
Security. Select Security to display a submenu.
2-15
Chapter 2
Managing Authorization
Managing the Policy Store Using Fusion Middleware Control
Use Fusion Middleware Control to manage the BI Publisher application policies and
application roles maintained in the policy store whether it is file-based or LDAP-based.
For more information about configuring an LDAP-based policy store, see Configuring a
New Policy Store and Credential Store Provider.
Caution:
Oracle recommends you make a copy of the original system-jazn-data.xml
policy file and place it in a safe location. Use the copy of the original file to
restore the default policy store configuration, if needed. Changes to the default
security configuration might lead to an unwanted state. The default installation
location is MW_HOME/user_projects/domain/your_domain/config/
fmwconfig.
The following are common policy store management tasks:
•
Modifying the membership of an application role. See Modifying Membership in an
Application Role.
•
Modifying the permission grants for an application role. See Changing Permission
Grants for an Application Policy.
•
Creating a new application role from the beginning. See Creating Application
Roles Using Fusion Middleware Control.
•
Creating a new application role based on an existing application role. See Creating
Application Roles Using Fusion Middleware Control.
Modifying Application Roles Using Fusion Middleware Control
Members can be added or deleted from an application role using Fusion Middleware
Control.
You must perform these tasks while in the WebLogic Domain that BI Publisher is
installed in. For example, bifoundation_domain.
Caution:
Be very careful when changing the permission grants and membership for the
default application roles. Changes could result in an unusable system.
Modifying Membership in an Application Role
Valid members of an application role are users, groups, or other application roles.
The process of becoming a member of an application role is called mapping. That is,
being mapped to an application role is to become a member of an application role.
2-16
Chapter 2
Managing Credentials
Best practice is to map groups instead of individual users to application roles for easier
maintenance.
To add or remove members from an application role:
1.
Log into Fusion Middleware Control, navigate to Security, then select Application
Roles to display the Application Roles page.
For information about navigating to the Security menu, see Accessing Oracle
Enterprise Manager Fusion Middleware Control.
2.
Choose Select Application Stripe to Search, then select the obi from the list.
Click the search icon next to Role Name.
3.
Select the cell next to the application role name and click Edit to display the Edit
Application Role page.
You can add or delete members from the Edit Application Role page. Valid
members are application roles, groups, and users.
4.
5.
Select from the following options:
•
To delete a member: From Members, select from Name the member to
activate the Delete button. Click Delete.
•
To add a member: Click the Add button that corresponds to the member type
being added. Select from Add Application Role, Add Group, and Add User.
If adding a member, complete Search and select from the available list. Use the
shuttle controls to move the member to the selected field. Click OK.
The added member displays in the Members column corresponding to the
application role modified in the Application Roles page.
Managing Credentials
Credentials used by the system are stored in a single secure credential store. Oracle
Wallet is the default credential store file (cwallet.sso).
The credential store alternatively can be LDAP-based, and Oracle Internet Directory is
the supported LDAP server in this release. You can configure and administer LDAPbased credential stores using Oracle Enterprise Manager Fusion Middleware Control
or WLST commands.
Each credential is uniquely identified by a map name and a key name. Each map
contains a series of keys, and each key is a credential. The combination of map name
and key name must be unique for all credential store entries.
BI Publisher supports the following credential maps:
•
oracle.bi.system: Contains the credentials that span the entire BI Publisher
platform.
•
oracle.bi.publisher: Contains the credentials used by only BI Publisher.
BI Publisher supports the following credential types:
•
Password: Encapsulates a user name and a password.
•
Generic: Encapsulates any customized data or arbitrary token, such as public key
certificates.
2-17
Chapter 2
Customizing the Default Security Configuration
To help you get started with your development environment, default credentials are
added to the file-based credential store during installation. Note that BI Publisher
credentials such as user passwords are stored in the identity store and managed with
its corresponding administrative interface.
Managing BI System User Credentials
If using Oracle Business Intelligence as a data store, BI Publisher establishes system
communication with it as BI system user.
Oracle Business Intelligence uses BI system user for trusted system communication.
To change the password of BI system user in the credential store (oracle.bi.system
credential map), see Security Guide for Oracle Business Intelligence Enterprise
Edition.
Customizing the Default Security Configuration
You can customize the default security configuration in various ways.
•
Configure a new authentication provider. See Configuring a New Authentication
Provider.
•
Configure new policy store and credential store providers. See Configuring a New
Policy Store and Credential Store Provider.
•
Migrate policies and credentials from one store to another. See Reassociating the
Policy Store and Credential Store.
•
Create new application roles. See Creating Application Roles Using Fusion
Middleware Control.
•
Create new application policies. See Creating Application Policies Using Fusion
Middleware Control.
•
Modify the permission grants for an application policy. See Changing Permission
Grants for an Application Policy.
Configuring a New Authentication Provider
You can configure another supported LDAP server to be the authentication provider.
Configuring BI Publisher to use an alternative external identity store is performed using
the Oracle WebLogic Server Administration Console. BI Publisher delegates
authentication and user population management to the authentication provider and
identity store configured for the domain it is a part of. For example, if configured to use
Oracle WebLogic Server's default authentication provider, then management is
performed in the Oracle WebLogic Server Administration Console. If configured to use
Oracle Internet Directory (OID), then the OID management user interface is used, and
so on.
If using an authentication provider other than the one installed as part of the default
security configuration, the default users and groups that are discussed in Default
Users and Groups are not automatically present. You can create users and groups
with names of your own choosing or re-create the default user and group names if the
authentication provider supports this. After this work is completed, you must map the
default BI Publisher application roles to different groups again. For example, if the
corporate LDAP server is being used as the identity store and you are unable to re-
2-18
Chapter 2
Customizing the Default Security Configuration
create the BI Publisher default users and groups in it, you must map the default
application roles to different groups specific to the corporate LDAP server. Use Fusion
Middleware Control to map the groups to application roles.
For information about how to configure a different authentication provider, see Oracle
WebLogic Server Administration Console Online Help and Administering Security for
Oracle WebLogic Server.
Configuring a New Policy Store and Credential Store Provider
The policy store and credential store can be file-based or LDAP-based.
The supported LDAP server for both stores in this release is Oracle Internet Directory.
The pre-requisites for using an LDAP-based store are the same as for both the policy
store and credential store. See Securing Applications with Oracle Platform Security
Services.
Reassociating the Policy Store and Credential Store
Migrating policies and credentials from one security store to another is called
reassociation.
Both policy store and credential store data can be reassociated (migrated) from a filebased store to an LDAP-based store, or from an LDAP-based store to another LDAPbased store.
Because the credential store and the policy store must both be of the same type, when
reassociating one store you must reassociate the other.
See Securing Applications with Oracle Platform Security Services.
Customizing the Policy Store
The Fusion Middleware Security model can be customized for your environment by
creating your own application policies and application roles.
Existing application roles can be modified by adding or removing members as needed.
Existing application policies can be modified by adding or removing permission grants.
For more information about managing application policies and application roles, see
Securing Applications with Oracle Platform Security Services.
Note:
Before creating a new application policy or application role and adding it to the
default BI Publisher security configuration, familiarize yourself with how
permission and group inheritance works. It is important when constructing a
role hierarchy that circular dependencies are not introduced. Best practice is to
leave the default security configuration in place and first incorporate your
customized application policies and application roles in a test environment. For
more information, see Permission Grants and Inheritance.
2-19
Chapter 2
Customizing the Default Security Configuration
Creating Application Roles Using Fusion Middleware Control
You can create a new application role or copy from an existing role using Fusion
Middleware Control.
Creating Application Roles
There are two methods for creating a new application role.
•
Create New — Creates new application role. You can add members when you
create the new role, or you can save the new role after naming it and later add
members.
•
Copy Existing — Creates a new application role by copying an existing
application role. The copy contains the same members as the original, and the
new role will be Grantee of the same application policy. You can modify the copy
as required when you create the new role.
Creating a New Application Role
1.
Log into Fusion Middleware Control, navigate to Security, and select Application
Roles to display the Application Roles page.
For information, see Accessing Oracle Enterprise Manager Fusion Middleware
Control.
2.
Choose obi from Application Stripe list. Click the search icon next to Role
Name.
You can view the BI Publisher application roles.
3.
Click Create to display the Create Application Role page. You can enter all
information at once or you can enter a Role Name, save it, and complete the
remaining fields later. Complete the fields as follows:
In the General section:
4.
5.
•
Role Name — Enter the name of the application role.
•
(Optional) Display Name — Enter the display name for the application role.
•
(Optional) Description — Enter a description for the application role.
In the Members section, Click Add to select the users, groups, or application roles
you want to map to the applications role.
a.
From the Type list, select Application Role, User, or Role you want to map
to the application role.
b.
Optionally, you can specify the criteria for Principal Name and Display
Name.
c.
Click the search icon next to Display Name.
d.
Select the principals from the Searched Principals table.
e.
Click OK.
Click OK to return to the Application Roles page.
The table at the bottom of the page displays the new application role.
2-20
Chapter 2
Customizing the Default Security Configuration
Creating an Application Role Based on an Existing role
1.
Log into Fusion Middleware Control, navigate to Security, and select Application
Roles to display the Application Roles page.
For information, see Accessing Oracle Enterprise Manager Fusion Middleware
Control.
2.
Choose obi from Application Stripe list. Click the search icon next to Role
Name.
You can view the BI Publisher application roles.
3.
Select an application role from the list to enable the action buttons.
4.
Click Create Like to display the Create Application Role Like page.
The Members section is completed with the same application roles, groups, or
users that are mapped to the original role.
5.
Complete the Role Name, Display Name, and Description fields.
For example, the figure below shows the MyNewRole application role based on
the BIContentAuthor role.
6.
Use Add and Delete to modify the members as appropriate and click OK.
The table at the bottom of the page displays the newly created application role.
For example, the figure below shows the MyNewRole based on the default
BIContentAuthor application role.
2-21
Chapter 2
Customizing the Default Security Configuration
Creating Application Policies Using Fusion Middleware Control
All BI Publisher permissions are provided and you cannot create new permissions.
Permission grants are controlled in the Fusion Middleware Control Application Policies
page.
Creating Application Policies
The permission grants are defined in an application policy. An application role, user, or
group, is then mapped to an application policy. This process makes the application
role, user, or group a Grantee of the application policy.
There are two methods for creating a new application policy:
•
Create New — Creates a new application policy and adds permissions to it.
•
Copy Existing — Creates a new application policy by copying an existing
application policy. You can name the copy, remove existing permissions, or add
new permissions as required.
Creating a New Application Policy
1.
Log in to Fusion Middleware Control, navigate to Security, and select Application
Policies to display the Application Policies page.
For information, see Accessing Oracle Enterprise Manager Fusion Middleware
Control.
2.
Choose obi from Application Stripe list. Click the search icon next to Principal
Name.
You can view the BI Publisher application policies. The Principal column displays
the name of the policy Grantee.
3.
Click Create to display the Create Application Grant page.
4.
To add permissions to the policy being created, click Add in the Permissions area
to display the Add Permission dialog.
2-22
Chapter 2
Customizing the Default Security Configuration
a.
Complete the Search section, and click the search icon next to the Resource
Name field.
All permissions located in the obi application stripe are displayed. For
information about the BI Publisher permissions, see Default Application Roles
and Permissions.
b.
Select the desired BI Publisher permissions, and click Continue. Selecting
non-BI Publisher permissions has no effect in the policy.
c.
If required, customize the permission and click Select.
The Permissions section display the selected permissions.
5.
To add an application role, user, or group to the policy being created, click Add in
the Grantee section..
In the Add Principal dialog, do the following:
6.
•
Complete the Search section, and click the search icon next to the Display
Name field.
•
Select the required principals from the Searched Principals list.
•
Click OK.
Click OK to return to the Application Policies page. You can view the Principal
(Grantee) and Permissions of the new policy in the table.
Creating an Application Policy Based on an Existing Policy
1.
Log in to Fusion Middleware Control, navigate to Security, and select Application
Policies to display the Application Policies page.
For information, see Accessing Oracle Enterprise Manager Fusion Middleware
Control.
2.
Choose obi from Application Stripe list. Click the search icon next to Principal
Name.
You can view the BI Publisher application policies. The Principal column displays
the name of the policy Grantee.
3.
Select an existing policy from the table.
For example, the figure below shows the selected BIServiceAdministrator Principal
(Grantee) selected and the activated Create Like button.
2-23
Chapter 2
Customizing the Default Security Configuration
4.
Click Create Like to display the Create Application Grant Like page. The
Permissions table displays the names of the permissions granted by the policy
selected.
5.
To remove any items, select it and click Delete.
6.
To add application role, user, or group to the policy, click Add in the Grantee area
to display the Add Principal dialog.
•
Complete the Search area and click the blue search icon next to the Display
Name field.
•
Select from the Searched Principals list.
•
Click OK.
The Application Policies page displays the Principal and Permissions of the policy.
Changing Permission Grants for an Application Policy
You can change one or more permissions granted by an application policy.
To add or remove permission grants from an application policy:
1.
Log in to Fusion Middleware Control, navigate to Security, then select Application
Policies to display the Application Policies page.
For information, see Accessing Oracle Enterprise Manager Fusion Middleware
Control.
2.
Choose Select Application Stripe to Search, then select obi from the list. Click
the search icon next to Role Name.
The BI Publisher application policies are displayed. The Principal column displays
the name of the policy Grantee.
3.
Select the name of the application role from the Principal column and click Edit.
2-24
Chapter 2
Customizing the Default Security Configuration
4.
Add or delete permissions from the Edit Application Grant view and click OK to
save the changes.
2-25
3
Alternative Security Options
This chapter describes alternative security options for BI Publisher, including Single
Sign-on (SSO), LDAP options, Oracle Access Manager (OAM), and Microsoft Active
Directory.
It covers the following topics:
•
About Alternative Security Options
•
Authentication and Authorization Options
•
Understanding BI Publisher Users, Roles, and Permissions
•
About Privileges to Use Functionality
•
About Catalog Permissions
•
How Functional Privileges and Permissions Work Together
•
About Access to Data Sources
•
Configuring Users, Roles, and Data Access
•
Security and Catalog Organization
•
Using LDAP with BI Publisher
•
Integrating with Microsoft Active Directory
•
Configuring BI Publisher with Single Sign-on (SSO)
•
Configuring SSO in an Oracle Access Manager Environment
•
Setting Up Oracle Single Sign-On
About Alternative Security Options
This chapter describes security concepts and options for a standalone implementation
of Oracle BI Publisher that is not installed as part of the Oracle Business Intelligence
Enterprise Edition.
Note the following:
•
If you have installed the Oracle BI Enterprise Edition, then see Security Guide for
Oracle Business Intelligence Enterprise Edition for information about security.
•
If you have installed BI Publisher on its own and you plan to use Oracle Fusion
Middleware Security, then see Understanding the Security Model. The following
topics will be of interest in this chapter:
•
–
About Catalog Permissions
–
About Access to Data Sources
To configure BI Publisher with these other Oracle security models:
–
Oracle BI Server security
–
Oracle E-Business Suite security
3-1
Chapter 3
Authentication and Authorization Options
–
Oracle Database security
–
Siebel CRM security
See Integrating with Other Oracle Security Models.
Use the information in this chapter to configure the following:
•
BI Publisher Security
•
Integration with an LDAP provider
Note:
Any identity store provider that is supported by Oracle WebLogic Server can
be configured to be used with BI Publisher. Configuring BI Publisher to use an
alternative external identity store is performed using the Oracle WebLogic
Server Administration Console. See Customizing the Default Security
Configuration.
•
Integration with a Single Sign-On provider
Authentication and Authorization Options
BI Publisher supports several options for authentication and authorization.
You can choose a single security model to handle both authentication and
authorization; or, you can configure BI Publisher to use a Single Sign-On provider or
LDAP provider for authentication with another security model to handle authorization.
Understanding BI Publisher Users, Roles, and Permissions
A user is assigned one or multiple roles.
A role can grant any or all of the following:
•
Privileges to use functionality
•
Permissions to perform actions on catalog objects
•
Access to data sources
You can create a hierarchy of roles by assigning roles to other roles. In this way the
privileges and permissions of multiple roles can roll up to higher level roles. The figure
below shows an example of the hierarchy structure of User, Role, and Folder.
3-2
Chapter 3
About Privileges to Use Functionality
Options for Configuring Users and Roles
There are three options for setting up users and roles.
•
Set up users and roles in the BI Publisher Security Center
For this option, follow the instructions in this section.
•
Configure BI Publisher with your LDAP server
For this option, see Configuring BI Publisher to Use an LDAP Provider for
Authentication and Authorization.
•
Set up users and roles in a supported Oracle security model. For this option, see
Integrating with Other Oracle Security Models.
About Privileges to Use Functionality
BI Publisher provides a set of functional roles to grant access to specific functionality
within the application. Assign these roles to users based on their need to perform the
associated tasks. These roles cannot be updated or deleted.
The table below shows the privileges granted to each functional role.
Role
Privilege
BI Publisher Scheduler
View Export History Schedule
BI Publisher Template
Designer
View Export History (public reports only) Enables access to
Layout Editor Enables log on from Template Builder
3-3
Chapter 3
About Catalog Permissions
Role
Privilege
BI Publisher Developer
View Export Schedule History Edit Report Enables access to
Layout Editor Enables log on from the Template Builder
Enables access to the Data Model Editor
BI Publisher Administrator
Enables the privileges of all other roles Grants access to the
Administration page and all administration tasks
Roles assigned these privileges cannot perform any actions on objects in the catalog
until they are also granted permissions on the catalog objects.
About Catalog Permissions
To perform the actions allowed by the functional roles above, a role must also be
granted permissions to access the objects in the catalog.
The table below describes permissions for roles.
Each of these permissions can be granted at the folder level to enable the operations
on all items within a folder.
Permission
Description
Read
Enables a role to display an object in the catalog. If the object resides
within a folder, a role must be granted the Read permission on the
object and its parent Folder.
Write
•
•
•
Delete
Enables a role to delete an object.
Run Report Online
Enables a role to run a report and view it in the report viewer.
Schedule Report
Enables a role to schedule a report.
View Report Output
Enables a role to access the Report Job History for a report.
Report — requires the BI Publisher Developer role
Data Model — requires the BI Publisher Developer role
Sub Template and Style Template - requires the BI Publisher
Developer Role or the BI Publisher Template Designer Role
It is important to note that for a report consumer to successfully run a report, his role
must have read access to every object that is referenced by the report.
For example, a report consumer must run a report in a folder named Reports. The
data model for this report, resides in a folder named Data Models. This report
references a Sub Template stored in a folder named Sub Templates, and also
references a Style Template stored in a folder named Style Templates. The report
consumer's role must be granted Read access to all of these folders and the
appropriate objects within.
How Functional Privileges and Permissions Work Together
Certain rules determine the behavior of privileges and permissions.
•
A role assigned a functional privilege cannot perform any actions in the catalog
until catalog permissions are also assigned
3-4
Chapter 3
About Access to Data Sources
•
A role can be assigned a set of permissions on catalog objects without being
assigned any functional privileges
•
If a role is assigned a functional privilege, when catalog permissions are assigned,
some permissions are inherited
A Role Must Be Assigned Catalog Permissions
A role assigned a functional role cannot perform any actions in the catalog until
catalog permissions are granted.
Note that the functional roles themselves (BI Publisher Developer, BI Publisher
Scheduler, and so on) cannot be directly assigned permissions in the catalog. The
functional roles must first be assigned to a custom role and then the custom role is
available in the catalog permissions table.
A Role Can Be Granted Catalog Permissions Only
The permissions available directly in the catalog enable running reports, scheduling
reports, and viewing report output.
Therefore if your enterprise includes report consumers who have no other reason to
access BI Publisher except to run and view reports, then the roles for these users
consist of catalog permissions only.
Inherited Permissions
When a role is assigned one of the functional roles, and that role is granted
permissions on a particular folder in the catalog, then some permissions are granted
automatically based on the functional role.
For example, assume that you create a role called Financial Report Developer. You
assign this role the BI Publisher Developer role. For this role to create reports in the
Financial Reports folder in the catalog, you grant this role Read, Write, and Delete
permissions on the folder. Because the BI Publisher Developer role includes the run
report, schedule report, and view report history privileges, these permissions are
automatically granted on any folder to which a role assigned the BI Publisher
Developer role is granted Read access.
About Access to Data Sources
A role must be granted access to a data source to view reports that run against the
data source or to build and edit data models that use the data source.
Add access to data sources in the Roles and Permissions page. See Granting Data
Access.
Configuring Users, Roles, and Data Access
This chapter details the procedures to configure users, roles, and data access.
•
Creating Roles
•
Creating Users and Assigning Roles to a User
3-5
Chapter 3
Configuring Users, Roles, and Data Access
•
Granting Catalog Permissions
•
Granting Data Access
Creating Roles
You create roles on the Administration page.
To create a new role in BI Publisher:
1.
Navigate to the BI Publisher Administration page.
2.
Under Security Center, click Roles and Permissions.
3.
Click Create Role.
4.
Enter a name for the role and optionally, enter a description.
5.
Click Apply.
6.
Click Assign Roles to assign roles to the user.
7.
Use the shuttle buttons to move Available Roles to Assigned Roles. Click
Apply.
8.
To add a role to a role, click Add Roles.
9.
Use the shuttle buttons to move Available Roles to Included Roles. Click Apply.
To add data sources to a role, see Granting Data Access.
Creating Users and Assigning Roles to a User
You create users in the Administration page.
To create users and assign roles to them:
1.
Navigate to the BI Publisher Administration page.
2.
Under Security Center, click Users.
3.
Click Create User.
4.
Add the User Name and Password for the user.
5.
Click Apply.
6.
Click Assign Roles to assign roles to the user.
7.
Use the shuttle buttons to move Available Roles to Assigned Roles. Click
Apply.
Granting Catalog Permissions
For a role to access an object in the catalog, the role must be granted Read
permissions on both the object and the folder in which the object resides.
Permissions can be granted at the folder level and applied to all the objects and
subfolders it contains, or applied to individual objects.
To grant catalog permissions to a role:
1.
Navigate to the Catalog.
3-6
Chapter 3
Configuring Users, Roles, and Data Access
2.
Locate the folder or object on which to grant permissions and click More. From the
menu (shown in the figure below), select Permissions. Alternatively, you can
select the folder and click Permissions in the Tasks region.
Note:
Permissions cannot be granted on the root Shared folder.
3.
On the Permissions dialog, click Create.
4.
On the Add Roles dialog, enter a search string to find a role, or simply click
Search to display all roles. Use the shuttle buttons to move roles from the
Available Roles list to the Selected Roles list.
3-7
Chapter 3
Configuring Users, Roles, and Data Access
5.
When finished, click OK to return to the Permissions dialog.
6.
On the Permissions dialog, configure the permissions required by the role.
Note the following:
7.
•
The icon next to the Report Developer role indicates that this role is assigned
one of the BI Publisher functional roles (in this case, the BI Publisher
Developer role).
•
Once the Report Developer role is assigned access to this folder, the following
permissions are automatically granted based on the privileges that comprise
the BI Publisher Developer Role: Run report online, Scheduler Report, View
Report Output.
If you are granting permissions on a Folder, select Apply permissions to items
within this folder, if the permissions should apply to all objects.
3-8
Chapter 3
Security and Catalog Organization
Granting Data Access
Roles must be granted access to data sources to run or schedule certain reports or to
create or edit certain data models.
A role must be granted access to a data source if the role must:
•
Run or schedule a report built on a data model that retrieves data from the data
source
•
Create or edit a data model that retrieves data from the data source
To grant a role access to a data source:
1.
Navigate to the BI Publisher Administration page.
2.
Under Security Center, click Roles and Permissions.
3.
On the Roles and Permissions page, locate the role, then click Add Data
Sources.
4.
On the Add Data Sources page you see a region for each of the following types of
data sources:
•
Database Connections
•
File Directories
•
LDAP Connections
•
OLAP Connections
5.
Use the shuttle buttons to move the required data sources from the Available
Data Sources list to the Allowed Data Sources list.
6.
When finished, click Apply.
Security and Catalog Organization
Because permissions are granted in the catalog, it is very important to be aware of this
design when creating roles for your organization and when structuring the catalog.
For example, assume that your organization requires the roles that are described in
the table below.
Role
Required Permissions
Sales Report Consumer
Needs to view and schedule Sales department reports.
Financial Report Consumer
Needs to view and schedule Financial department reports.
Executive Report Consumer
Needs to consume both Sales and Financial reports and
executive level reports.
Sales Report Developer
Needs to create data models and reports for Sales department
only.
Financials Report Developer
Needs to create data models and reports for Financials
department only.
Layout Designer
Needs to design report layouts for all reports.
You might consider setting up the catalog structure as described in the table below.
3-9
Chapter 3
Security and Catalog Organization
Folder
Contents
Sales Reports
All reports for Sales Report Consumer. Also contains any Sub
Templates and Style Templates associated with Sales reports.
Sales Data Models
All data models for Sales reports.
Financials Reports
All reports for Financials Report Consumer. Also contains any Sub
Templates and Style Templates associated with Financials
reports.
Financials Data Models
All data models for Financials reports
Executive Reports
All executive-level reports and data models.
Set up the roles as follows:
Example Role Configuration
Sales Report Consumer:
Grant catalog permissions:
•
To the Sales Reports folder add the Sales Report Consumer and grant:
Read
Schedule Report
Run Report Online
View Report Online
Select Apply permissions to items within this folder
•
To the Sales Data Models folder add the Sales Report Consumer and grant:
Read
Grant Data Access:
On the Roles page, locate the role, then click Add Data Sources. Add all data
sources used by Sales reports.
Financials Report Consumer
Grant catalog permissions:
•
To the Financials Reports folder add the Financials Report Consumer and grant:
Read
Schedule Report
Run Report Online
View Report Online
Select Apply permissions to items within this folder
•
To the Financials Data Models folder add the Financials Report Consumer and
grant:
Read
Grant Data Access:
3-10
Chapter 3
Security and Catalog Organization
On the Roles page, locate the role, then click Add Data Sources. Add all data
sources used by Financials reports.
Executive Report Consumer
Assign Roles:
On the Roles tab, assign the Executive Report Consumer the Sales Report Consumer
and the Financials Report Consumer roles.
Grant catalog permissions:
•
To the Executive Reports folder add the Executive Report Consumer and grant:
Read
Schedule Report
Run Report Online
View Report Online
Select Apply permissions to items within this folder
Grant Data Access:
On the Roles tab, locate the role, then click Add Data Sources. Add all data sources
used by Executive reports.
Sales Report Developer
Assign Roles:
On the Roles tab, assign the Sales Report Developer the BI Publisher Developer Role
and the BI Publisher Template Designer Role.
Grant Data Access:
On the Roles tab, locate the Sales Report Developer and click Add Data Sources.
Add all data sources from which Sales data models are built.
Grant Catalog Permissions:
•
In the catalog, to the Sales Data Models folder add the Sales Report Developer
and grant:
Read, Write, Delete
•
To the Sales Reports folder, add the Sales Report Developer and grant:
Read, Write, Delete
Financials Report Developer
Assign Roles:
On the Roles tab, assign the Financials Report Developer the BI Publisher Developer
Role, and the BI Publisher Template Designer Role.
Grant Data Access:
On the Roles tab, locate the Financials Report Developer and click Add Data
Sources. Add all data sources from which Financials data models are built.
Grant Catalog Permissions:
3-11
Chapter 3
Using LDAP with BI Publisher
•
In the catalog, to the Financials Data Models folder add the Financials Report
Developer and grant:
Read, Write, Delete
•
To the Financials Reports folder, add the Financials Report Developer and grant:
Read, Write, Delete
Layout Designer
Assign Roles:
On the Roles tab, assign the Layout Designer the BI Publisher Template Designer
Role and the BI Publisher Developer Role.
Grant Catalog Permissions:
•
In the catalog, to the Financials Data Models and the Sales Data Models folders
add the Layout Designer Role and grant:
Read
•
To the Financials Reports and Sales Reports folders, add the Layout Designer and
grant:
Read, Write, Delete
Using LDAP with BI Publisher
You can use BI Publisher with an LDAP provider for authentication only or for both
authentication and authorization.
Note:
By default, BI Publisher allows every LDAP user to log in to the system even
when no BI Publisher-specific roles are assigned to the user. Users cannot
perform any functions that require roles, such as creating reports or data
models; however if a user is assigned a role that is assigned permissions on
catalog objects (such as traverse and open) the user can perform those tasks.
To prevent users from logging in to BI Publisher unless they have a BI
Publisher role assigned, see Disabling Users Without BI Publisher-Specific
Roles from Logging In.
•
Configuring BI Publisher to Use an LDAP Provider for Authentication Only
•
Configuring BI Publisher to Use an LDAP Provider for Authentication and
Authorization
Configuring BI Publisher to Use an LDAP Provider for Authentication
Only
Configure BI Publisher to use an LDAP provider for authentication in conjunction with
another security model for authorization.
3-12
Chapter 3
Using LDAP with BI Publisher
1.
On the Administration page, under Security Center, click Security Configuration.
2.
Create a Local Superuser.
Enter a Superuser Name and Password and select Enable Local Superuser
check box. Enabling a local superuser ensures that you can access the
Administration page of BI Publisher in case of security model configuration errors.
3.
Scroll down to the Authentication region. Select the Use LDAP check box.
4.
Enter the following:
•
URL
For example: ldap://example.com:389/
If you are using LDAP over SSL, then note the following:
–
the protocol is ldaps
–
the default port is 636
An example URL would be: ldaps://example.com:636/
•
Administrator Username and Password for the LDAP server
The Administrator user entered here must also be a member of the
XMLP_ADMIN group.
•
Distinguished Name for Users
For example: cn=Users,dc=example,dc=com
The distinguished name values are case-sensitive and must match the
settings in the LDAP server.
•
JNDI Context Factory Class
The default value is com.sun.jndi.ldap.LdapCtxFactory
•
Attribute used for Login Username
Enter the attribute that supplies the value for the Login user name. This is also
known as the Relative Distinguished Name (RDN). This value defaults to cn.
•
Attribute used for user matching with authorization system - enter the
attribute that supplies the value to match users to the authorization system.
For example, orcleguid.
5.
Click Apply.
6.
Restart the BI Publisher server.
Configuring BI Publisher to Use an LDAP Provider for Authentication
and Authorization
BI Publisher can be integrated with the LDAP provider to manage users and report
access.
Create the users and roles within the LDAP server, then configure the BI Publisher
server to access the LDAP server.
In the BI Publisher security center module, assign folders to those roles. When users
log in to the server, they have access to those folders and reports assigned to the
LDAP roles.
3-13
Chapter 3
Using LDAP with BI Publisher
Integrating the BI Publisher server with Oracle LDAP consists of three main tasks:
1.
Set up users and roles in the LDAP provider
2.
Configure BI Publisher to recognize the LDAP server
3.
Assign catalog permissions and data access to roles
For information on supported LDAP servers, see System Requirements and
Certification for the most up-to-date information on supported hardware and software.
Setting Up Users and Roles in the LDAP Provider
This procedure must be performed in the LDAP provider. See the documentation for
the provider for details on how to perform these tasks.
To set up users and roles:
1.
In the Domain root node of the LDAP provider, create the roles that are described
in the table below to integrate with BI Publisher. See Understanding BI Publisher
Users, Roles, and Permissions for full descriptions of the required functional roles.
BI Publisher System Group
Description
XMLP_ADMIN
The administrator role for the BI Publisher server. You
must assign the Administrator account used to access
your LDAP server the XMLP_ADMIN group.
XMLP_DEVELOPER
Allows users to create and edit reports and data
models.
XMLP_SCHEDULER
Allows users to schedule reports.
XMLP_TEMPLATE_DESIGNER
Allows users to connect to the BI Publisher server from
the Template Builder for Word and to upload and
download templates. Allows users to design layouts
using the BI Publisher Layout Editor.
2.
Create other functional roles as required by your implementation (for example: HR
Manager, Warehouse Clerk, or Sales Manager), and assign the appropriate BI
Publisher functional roles.
3.
Assign roles to users.
Note:
Ensure that you assign the Administrator account the XMLP_ADMIN role.
3-14
Chapter 3
Using LDAP with BI Publisher
Configuring the BI Publisher Server to Recognize the LDAP Server
To configure the BI Publisher server to recognize the LDAP server, update the
Security properties in the BI Publisher Administration page.
Note:
Ensure that you understand your site's LDAP server configuration before
entering values for the BI Publisher settings.
To configure the BI Publisher Server for the LDAP Server:
1.
On the Administration page, under Security Center, click Security Configuration.
2.
Create a Local Superuser.
Enter a Superuser Name and Password and select Enable Local Superuser
check box. Enabling a local superuser ensures that you can access the
Administration page of BI Publisher in case of security model configuration errors.
3.
Scroll down to the Authorization region. Select LDAP for the Security Model.
4.
Enter the following:
•
URL
For example: ldap://example.com:389/
If you are using LDAP over SSL, then note the following:
–
the protocol is "ldaps"
–
the default port is 636
For example: ldaps://example.com:636/
•
Administrator Username and Password for the LDAP server
The Administrator user entered here must also be a member of the
XMLP_ADMIN group.
•
Distinguished Name for Users
For example: cn=Users,dc=example,dc=com
The distinguished name values are case-sensitive and must match the
settings in the LDAP server.
•
Distinguished Name for Groups
For example: cn=Groups,dc=us,dc=oracle,dc=com
The default value is
cn=OracleDefaultDomain,cn=OracleDBSecurity,cn=Products,cn=OracleConte
xt,dc=example,dc=com
•
Group Search Filter
The default value is (&(objectclass=groupofuniquenames)(cn=*))
•
Group Attribute Name
3-15
Chapter 3
Using LDAP with BI Publisher
The default value is cn
•
Group Member Attribute Name
The default value is uniquemember
•
Member of Group Attribute Name
(Optional) Set this attribute only if memberOf attribute is available for User and
Group. Group Member Attribute is not required when this attribute is available.
Example: memberOf or wlsMemberOf
•
Group Description Attribute Name
The default value is description
•
JNDI Context Factory Class
The default value is com.sun.jndi.ldap.LdapCtxFactory
•
Group Retrieval Page Size
Setting this value enables support of the LDAPv3 control extension for simple
paging of search results. By default, the BI Publisher server does not use
pagination. This value determines the number of results to return on a page
(for example, 200). Your LDAP server must support control type
1.2.840.113556.1.4.319 to support this feature, such as Oracle Internet
Directory 10.1.4. Ensure that you check your LDAP server documentation for
support of this control type before entering a value.
•
Attribute used for Login Username
Enter the attribute that supplies the value for the Login user name. This is also
known as the Relative Distinguished Name (RDN). This value defaults to cn.
•
•
Automatically clear LDAP cache - to schedule the automatic refresh of the
LDAP cache the LDAP cache per a designated interval, select this box. After
you select this box the following additional fields become enabled:
–
Enter an integer for Ldap Cache Interval. For example, to clear the LDAP
cache once a day, enter 1.
–
Select the appropriate Ldap Cache Interval Unit: Day, Hour, or Minute.
Default User Group Name
(Optional) Use this option if your site has the requirement to allow all
authenticated users access to a set of folders, reports, or other catalog
objects. The user group name that you enter here is added to all authenticated
users. Any catalog or data source permissions that you assign to this default
user group are granted to all users.
•
Attribute Names for Data Query Bind Variables
(Optional) Use this property to set attribute values to be used as bind variables
in a data query. Enter LDAP attribute names separated by a commas for
example: memberOf, primaryGroupID,mail
See Creating Bind Variables from LDAP User Attribute Values in Data
Modeling Guide for Oracle Business Intelligence Publisher.
5.
Click Apply. Restart the BI Publisher server.
The figure below shows a sample of the LDAP security model entry fields from the
Security Configuration page.
3-16
Chapter 3
Using LDAP with BI Publisher
If you are configuring BI Publisher to use LDAP over SSL, then you must also
configure Java keystore to add the server certificate to JVM. See Configuring BI
Publisher for Secure Socket Layer (SSL) Communication.
Assigning Data Access and Catalog Permissions to Roles
Assign data access and catalog permissions to roles in the Administration page.
To assign data access and catalog permissions to roles:
1.
Log in to BI Publisher as a user assigned the XMLP_ADMIN role in the LDAP
provider.
2.
On the Administration page, click Roles and Permissions.
You see the roles that you created in the LDAP provider to which you assigned the
XMLP_ roles. Note the following:
3.
•
The XMLP_X roles are not shown because these are controlled through the
LDAP interface.
•
The Users tab is no longer available under the Security Center because users
are now managed through your LDAP interface.
•
Roles are not updatable in the BI Publisher interface, except for adding data
sources.
Click Add Data Sources to add BI Publisher data sources to the role. A role must
be assigned access to a data source to run reports from that data source or to
build data models from the data source. For more information see Granting Data
Access.
3-17
Chapter 3
Integrating with Microsoft Active Directory
4.
Grant catalog permissions to roles. See About Catalog Permissions and Granting
Catalog Permissions for details on granting catalog permissions to roles.
Users can now log in using their LDAP username/password.
Disabling Users Without BI Publisher-Specific Roles from Logging In
To disable users without BI Publisher-specific roles from logging in to the BI Publisher
server, set a configuration property in the xmlp-server-config.xml file.
The xmlp-server-config.xml file is located at:
$DOMAIN_HOME/bidata/components/bipublisher/repository/Admin/Configuration/xmlpserver-config.xml
In the xmlp-server-config.xml file, add the following property and setting:
<property name="REQUIRE_XMLP_ROLE_FOR_LOGIN" value="true"/>
Integrating with Microsoft Active Directory
Microsoft Active Directory supports the LDAP interface and therefore can be
configured with BI Publisher using LDAP Security.
•
Configuring the Active Directory
•
Configuring BI Publisher
•
Logging In to BI Publisher Using the Active Directory Credentials
•
Assigning Data Access and Catalog Permissions to Roles
Configuring the Active Directory
Configure support for Active Directory by adding users and system groups.
To configure the active directory:
1.
Add users who must access BI Publisher.
Add the users under "Users" or any other organization unit in the Domain Root.
2.
Add the BI Publisher system groups. The Scope of the groups must be Domain
Local.
The table below describes the BI Publisher system groups that must be added.
BI Publisher System Group
Description
XMLP_ADMIN
The administrator role for the BI Publisher server. You
must assign the Administrator account used to access
your LDAP server the XMLP_ADMIN group.
XMLP_DEVELOPER
Allows users to create and edit reports and data
models.
XMLP_SCHEDULER
Allows users to schedule reports.
3-18
Chapter 3
Integrating with Microsoft Active Directory
3.
BI Publisher System Group
Description
XMLP_TEMPLATE_DESIGNER
Allows users to connect to the BI Publisher server from
the Template Builder for Word and to upload and
download templates. Allows users to design layouts
using the BI Publisher Layout Editor.
Grant BI Publisher system groups to global groups or users.
You can grant BI Publisher system groups directly to users or through global
groups.
Example 1: Grant Users the BI Publisher Administrator Role
1.
Under the Active Directory User and Computers, open the XMLP_ADMIN group
and click the Members tab.
2.
Click Add to add users who need to BI Publisher Administrator privileges.
Example 2: Grant Users Access to Scheduling Reports
The "HR Manager" global group is defined under "Users".
All users in this group need to schedule reports.
To achieve this, add HR Manager as a Member of the XMLP_SCHEDULER group.
Configuring BI Publisher
You configure BI Publisher on the Administration page.
To configure BI Publisher:
1.
On the Administration page, click Security Configuration.
2.
Set up a Local Superuser if one has not been configured. This is very important in
case the security configuration fails, you must still be able to log in to BI Publisher
using the Superuser credentials.
3.
In the Authorization region of the page, select LDAP from the Security Model list.
4.
Enter the details for the Active Directory server, as described in Configuring the BI
Publisher Server to Recognize the LDAP Server, noting the following specific
information for Active Directory:
•
Set Group Search Filter objectclass to "group"
•
Set Member of Group Member Attribute Name to "memberOf" (Group
Member Attribute Name can be left blank).
•
Set Attribute used for Login Username to "sAMAccountName".
•
If you are using LDAP over SSL note the following:
–
the protocol is ldaps
–
the default port is 636
An example URL would be: ldaps://example.com:636/
The figure below shows an example configuration highlighting the
recommendations stated above.
3-19
Chapter 3
Integrating with Microsoft Active Directory
5.
Click Apply. Restart the BI Publisher application.
If you are configuring BI Publisher to use LDAP over SSL, then you must also
configure Java keystore to add the server certificate to JVM. For more information, see
Configuring BI Publisher for Secure Socket Layer (SSL) Communication.
Logging In to BI Publisher Using the Active Directory Credentials
The User login name defined in Active Directory Users and Computers >User
Properties >Account is used for the BI Publisher login name.
Add the Domain to the user name to log in to BI Publisher. For example:
"[email protected]".
Note the following:
•
The Attribute used for Login Username can be sAMAccountName instead of
userPrincipalName.
•
You must use sAMAccountName for the Attribute used for Login Username
when the "User logon name (pre-Windows 2000)" is required to use for the BI
Publisher login username.
•
User names must be unique across all organization units.
Assigning Data Access and Catalog Permissions to Roles
You assign data access and catalog permissions to roles on the Administration page.
To assign data access and catalog permissions to roles:
1.
Log in to BI Publisher as a user assigned the XMLP_ADMIN role in Active
Directory.
3-20
Chapter 3
Configuring BI Publisher with Single Sign-on (SSO)
2.
On the Administration page, click Roles and Permissions.
You see the roles that you created in Active Directory to which you assigned the
XMLP_ roles. Note the following:
•
The XMLP_X roles are not shown because these are controlled through the
Active Directory interface.
•
The Users tab is no longer available under the Security Center because users
are now managed through Active Directory.
•
Roles are not updatable in the BI Publisher interface, except for adding data
sources.
3.
Click Add Data Sources to add BI Publisher data sources to the role. A role must
be assigned access to a data source to run reports from that data source or to
build data models from the data source. For more information see Granting Data
Access.
4.
Grant catalog permissions to roles. See About Catalog Permissions and Granting
Catalog Permissions for details on granting catalog permissions to roles.
Configuring BI Publisher with Single Sign-on (SSO)
Integrating a single sign-on (SSO) solution enables a user to log on (sign-on) and be
authenticated once.
Thereafter, the authenticated user is given access to system components or resources
according to the permissions and privileges granted to that user. BI Publisher can be
configured to trust incoming HTTP requests authenticated by a SSO solution that is
configured for use with Oracle Fusion Middleware and Oracle WebLogic Server. For
information about configuring SSO for Oracle Fusion Middleware, see Securing
Applications with Oracle Platform Security Services.
When BI Publisher is configured to use SSO authentication, it accepts authenticated
users from whatever SSO solution Oracle Fusion Middleware is configured to use. If
SSO is not enabled, then BI Publisher challenges each user for authentication
credentials. When BI Publisher is configured to use SSO, a user is first redirected to
the SSO solution's login page for authentication.
Configuring BI Publisher to work with SSO authentication requires minimally that the
following be done:
•
Oracle Fusion Middleware and Oracle WebLogic Server are configured to accept
SSO authentication. Oracle Access Manager is recommended in production
environments.
•
BI Publisher is configured to trust incoming messages.
•
The HTTP header information required for identity propagation with SSO
configurations (namely, user identity and SSO cookie) is specified and configured.
How BI Publisher Operates with SSO Authentication
After SSO authorization has been implemented, BI Publisher operates as if the
incoming web request is from a user authenticated by the SSO solution. User
personalization and access controls such as data-level security are maintained in this
environment.
3-21
Chapter 3
Configuring SSO in an Oracle Access Manager Environment
Tasks for Setting Up SSO Authentication with BI Publisher
Refer to the table below for SSO authentication configuration tasks and links providing
more information.
Task
Description
For More Information
Configure Oracle
Access Manager as
the SSO
authentication
provider.
Configure Oracle Access Manager Configuring SSO in an Oracle
to protect the BI Publisher URL
Access Manager Environment
entry points.
See Securing Applications with
Oracle Platform Security Services
Configure the HTTP
proxy.
Configure the web proxy to
forward requests from BI Publisher
to the SSO provider.
Configure a new
authenticator for
Oracle WebLogic
Server.
Configure the Oracle WebLogic
Server domain in which BI
Publisher is installed to use the
new identity store.
Configure a new
identity asserter for
Oracle WebLogic
Server.
Configure the Oracle WebLogic
Server domain in which BI
Publisher is installed to use the
SSO provider as an asserter.
Enable BI Publisher
to accept SSO
authentication.
Enable the SSO provider
configured to work with BI
Publisher.
Configuring a New Authenticator for
Oracle WebLogic Server
See Oracle WebLogic Server
Administration Console Online Help
Configuring BI Publisher for Oracle
Fusion Middleware Security
Note:
For an example of an Oracle Business Intelligence SSO installation scenario,
see Enterprise Deployment Guide for Oracle Business Intelligence.
Configuring SSO in an Oracle Access Manager Environment
Configure Oracle Access Manager as the SSO authentication provider for Oracle
Fusion Middleware with WebLogic Server.
See Securing Applications with Oracle Platform Security Services .
After the Oracle Fusion Middleware environment is configured, in general the following
must be done to configure BI Publisher:
•
Configure the SSO provider to protect the BI Publisher URL entry points.
•
Configure the web server to forward requests from BI Publisher to the SSO
provider.
•
Configure the new identity store as the main authentication source for the Oracle
WebLogic Server domain in which BI Publisher has been installed. For more
information, see Configuring a New Authenticator for Oracle WebLogic Server.
3-22
Chapter 3
Configuring SSO in an Oracle Access Manager Environment
•
Configure the Oracle Access Manager domain in which BI Publisher is installed to
use an Oracle Access Manager asserter. For more information, see Configuring
OAM as a New Identity Asserter for Oracle WebLogic Server.
•
After configuration of the SSO environment is complete, enable SSO
authentication for BI Publisher. For more information, see Configuring BI Publisher
for Oracle Fusion Middleware Security.
Configuring a New Authenticator for Oracle WebLogic Server
After installing BI Publisher, the Oracle WebLogic Server embedded LDAP server is
the default authentication source (identity store). To use a new identity store (for
example, OID), as the main authentication source, you must configure the Oracle
WebLogic Server domain (where BI Publisher is installed).
For more information about configuring authentication providers in Oracle WebLogic
Server, see Administering Security for Oracle WebLogic Server.
To configure a new authenticator in Oracle WebLogic Server:
1.
Log in to Oracle WebLogic Server Administration Console and click Lock & Edit in
the Change Center.
2.
Select Security Realms from the left pane and click myrealm.
The default Security Realm is named myrealm.
3.
Display the Providers tab, then display the Authentication sub-tab.
4.
Click New to launch the Create a New Authentication Provider page.
Complete the fields as follows:
•
Name: OID Provider, or a name of your choosing.
•
Type: OracleInternetDirectoryAuthenticator
•
Click OK to save the changes and display the authentication providers list
updated with the new authentication provider.
5.
Click the newly added authenticator in the authentication providers table.
6.
Navigate to Settings, then select the Configuration\Commontab:
7.
•
Select SUFFICIENT from the Control Flag list.
•
Click Save.
Display the Provider Specific tab and specify the following settings using
appropriate values for your environment:
Section Name
Field Name
Description
Connection
Host
The LDAP host name. For example,
<localhost>.
Connection
Port
The LDAP host listening port
number. For example, 6050.
Connection
Principal
The distinguished name (DN) of the
user that connects to the LDAP
server. For example, cn=orcladmin.
3-23
Chapter 3
Configuring SSO in an Oracle Access Manager Environment
Section Name
Field Name
Description
Connection
Credential
The password for the LDAP
administrative user entered as the
Principal.
Users
User Base DN
The base distinguished name (DN)
of the LDAP server tree that contains
users. For example, use the same
value as in Oracle Access Manager.
Users
All Users Filter
The LDAP search filter. For example,
(&(uid=*) (objectclass=person)). The
asterisk (*) filters for all users. Click
More Info... for details.
Users
User From Name Filter
The LDAP search filter. Click More
Info... for details.
Users
User Name Attribute
The attribute that you want to use to
authenticate (for example, cn, uid, or
mail). Set as the default attribute for
user name in the directory server.
For example, uid.
Note: The value that you specify
here must match the User Name
Attribute that you are using in the
authentication provider.
Groups
Group Base DN
The base distinguished name (DN)
of the LDAP server tree that contains
groups (same as User Base DN).
General
GUID attribute
The attribute used to define object
GUIDs in LDAP.
orclguid
8.
Click Save.
9.
Perform the following steps to set up the default authenticator for use with the
Identity Asserter:
a.
At the main Settings for myrealm page, display the Providers tab, then display
the Authentication sub-tab, and then select DefaultAuthenticator to display
its configuration page.
b.
Display the Configuration\Common tab and select 'SUFFICIENT' from the
Control Flag list.
c.
Click Save.
10. Perform the following steps to reorder Providers:
a.
In the Providers tab, click Reorder to display the Reorder Authentication
Providers page
b.
Select a provider name and use the arrow buttons to order the list of providers
as follows:
c.
•
OID Authenticator (SUFFICIENT)
•
OAM Identity Asserter (REQUIRED)
•
Default Authenticator (SUFFICIENT)
Click OK to save your changes.
3-24
Chapter 3
Configuring SSO in an Oracle Access Manager Environment
11. In the Change Center, click Activate Changes.
12. Restart Oracle WebLogic Server.
Configuring OAM as a New Identity Asserter for Oracle WebLogic
Server
The Oracle WebLogic Server domain in which BI Publisher is installed must be
configured to use an Oracle Access Manager asserter.
For more information about creating a new asserter in Oracle WebLogic Server, see
Oracle WebLogic Server Administration Console Online Help.
To configure Oracle Access Manager as the new asserter for Oracle WebLogic
Server:
1.
Log in to Oracle WebLogic Server Administration Console.
2.
In Oracle WebLogic Server Administration Console, select Security Realms from
the left pane and click the realm you are configuring. For example, myrealm.
Select Providers.
3.
Click New. Complete the fields as follows:
•
Name: OAM Provider, or a name of your choosing.
•
Type: OAMIdentityAsserter.
4.
Click OK.
5.
Click Save.
6.
In the Providers tab, perform the following steps to reorder Providers:
a.
Click Reorder
b.
In the Reorder Authentication Providers page, select a provider name, and
use the arrows beside the list to order the providers as follows:
c.
•
OID Authenticator (SUFFICIENT)
•
OAM Identity Asserter (REQUIRED)
•
Default Authenticator (SUFFICIENT)
Click OK to save your changes.
7.
In the Change Center, click Activate Changes.
8.
Restart Oracle WebLogic Server.
You can verify that Oracle Internet Directory is the new identity store (default
authenticator) by logging back into Oracle WebLogic Server and verifying the
users and groups stored in the LDAP server appear in the console.
9.
Use Fusion Middleware Control to enable SSO authentication.
3-25
Chapter 3
Setting Up Oracle Single Sign-On
Configuring BI Publisher for Oracle Fusion Middleware Security
After Oracle WebLogic Server has been configured, navigate to the BI Publisher
Administration Security Configuration page. In the Authorization region, select Oracle
Fusion Middleware as the Security Model.
Setting Up Oracle Single Sign-On
Set up Oracle Single Sign-On in the Identity Store Configuration page.
To set up Oracle Single Sign-On, first configure WebLogic Server using the
instructions in Administering Security for Oracle WebLogic Server. BI Publisher must
be configured to use Oracle Internet Directory as the default LDAP server.
Note:
When using Oracle SSO, BI Publisher assumes that a login user name can be
derived from Osso-User-Dn, which is HTTP Header value. For example, if the
Osso-User-Dn on HTTP Header looks like this:
cn=admin,cn=users, dc=us,dc=oracle,dc=com
Then BI Publisher assumes the value of first cn= is the login user name (that
is, "admin" in this case).
Therefore if your Osso-User-Dn does not contain a login user name as the first
cn value, then select "Other SSO Type" to configure the settings (even if you
use Oracle SSO).
Setup Procedure
You set up SSO in the mod_osso.conf file.
To set up SSO:
1.
Modify the application server configuration file to protect the xmlpserver. See
Securing Applications with Oracle Platform Security Services.
2.
In the mod_osso.conf add a new "Location" directive as follows:
<!-- Protect xmlpserver -->
<Location /xmlpserver>
require valid-user
3-26
Chapter 3
Setting Up Oracle Single Sign-On
AuthType Basic
</Location>
3.
To allow Web service communication between BI Publisher and its client
component (the Template Builder) you must make additional modifications to the
mod_osso.conf file. To open up the xmlpserver to allow these Web services, enter
the following directives:
<Location /xmlpserver/services/>
require valid-user
AuthType Basic
Allow from All
Satisfy any
</Location>
<Location /xmlpserver/report_service/>
require valid-user
AuthType Basic
Allow from All
Satisfy any
</Location>
Location /xmlpserver/ReportTemplateService.xls/>
require valid-user
AuthType Basic
Allow from All
Satisfy any
</Location>
4.
For integration with Oracle BI Presentation Services, you must disable SSO for
Web services between the BI Presentation Services server and the BI Publisher
server. If you made this entry when performing the previous step, then you do not
need to repeat this setup.
To open up the xmlpserver to allow the Web service, enter the following directive
in the mod_osso.conf file:
<Location /xmlpserver/services/>
require valid-user
AuthType Basic
Allow from All
Satisfy any
</Location>
A sample mod_osso.conf file with the entries discussed in this section is shown
below:
LoadModule osso_module libexec/mod_osso.so
<IfModule mod_osso.c>
OssoIpCheck off
OssoIdleTimeout off
OssoConfigFile /home/as1013/ohome/Apache/Apache/conf/osso/osso.conf
<Location /xmlpserver>
require valid-user
AuthType Basic
</Location>
<Location /xmlpserver/services/>
require valid-user
AuthType Basic
3-27
Chapter 3
Setting Up Oracle Single Sign-On
Allow from All
Satisfy any
</Location>
<Location /xmlpserver/report_service/>
require valid-user
AuthType Basic
Allow from All
Satisfy any
</Location>
Location /xmlpserver/ReportTemplateService.xls/>
require valid-user
AuthType Basic
Allow from All
Satisfy any
</Location>
<Location /xmlpserver/Guest/>
require valid-user
AuthType Basic
Allow from All
Satisfy any
</Location>
#
# Insert Protected Resources: (see Notes below for how to protect resources)
#
#______#
# Notes
#
#______#
# 1. Here's what you need to add to protect a resource,
#
e.g. <ApacheServerRoot>/htdocs/private:
#
#
<Location /private>
#
require valid-user
#
AuthType Basic
#
</Location>
#
</IfModule>
#
# If you would like to have short hostnames redirected to
# fully qualified hostnames to allow clients that need
# authentication through mod_osso to be able to enter short
# hostnames into their browsers uncomment out the following
# lines
#
#PerlModule Apache::ShortHostnameRedirect
#PerlHeaderParserHandler Apache::ShortHostnameRedirect
5.
Restart the HTTP server.
6.
In BI Publisher, set up the Single Sign-Off URL on the BI Publisher Security
Configuration page.
On the Administration page, click Security Configuration. In the Authentication
region:
3-28
Chapter 3
Setting Up Oracle Single Sign-On
•
Select Use Single Sign-On.
•
From the Single Sign-On Type list, select Oracle Single Sign On.
•
Enter the Single Sign-Off URL with the value you wrote down in the
preceding step. The remaining fields are not applicable to Oracle SSO.
A sample BI Publisher Security Configuration page is shown below.
7.
Create a BI Publisher Local Superuser to ensure access to BI Publisher
regardless of your selected security configuration. See Enabling a Local
Superuser for more information.
8.
Click Apply.
9.
Restart the application through the Oracle Fusion Middleware Control page.
10. Enter the URL to access the BI Publisher Enterprise application, and you are
redirected to the SSO login page.
3-29
4
Other Security Topics
This chapter describes additional BI Publisher security topics including SSL
configuration, proxy settings, enabling a local superuser, and enabling a guest user.
It covers the following topics:
•
Enabling a Local Superuser
•
Enabling a Guest User
•
Configuring BI Publisher for Secure Socket Layer (SSL) Communication
•
Enabling Secure Cookies
•
Configuring Proxy Settings
•
Restricting Embedding of BI Publisher in iframes
Enabling a Local Superuser
BI Publisher enables you to define an administration Superuser.
Using the Superuser credentials you can directly access the BI Publisher
administrative functions without logging in through the defined security model.
Set up this Superuser to ensure access to all administrative functions in case of
failures with the configured security model. It is highly recommended that you set up a
Superuser. Catalog operations are not available to a Superuser, if BI Publisher is
configured to use Oracle Business Intelligence Enterprise Edition catalog,
To enable a local superuser:
1.
Click Administration.
2.
Under Security Center, click Security Configuration.
3.
Under Local Superuser, select the box and enter the credentials for the Superuser,
as shown below.
4-1
Chapter 4
Enabling a Guest User
4.
Restart the BI Publisher application.
Enabling a Guest User
BI Publisher allows you configure public access to specific reports by defining a
"Guest" folder. Any user can access the reports in this folder without entering
credentials.
Note:
Guest access is not supported when BI Publisher uses a shared catalog or is
installed with Oracle Business Intelligence Enterprise Edition.
Guest access is not supported with Single Sign-On.
All objects that are required to view a report must be present in the Guest folder
because the Guest folder is the only folder the guest user has any access rights to.
Therefore the report and the data model must be present in the Guest folder and Sub
Templates and Style Templates, if applicable. The guest user must have read access
only.
The Guest user must also be granted access to the report data source.
To enable guest access:
1.
Under Shared Folders, create the folder to which you want to grant public access.
2.
Click Administration.
3.
Under Security Center, select Security Configuration.
4.
Under Guest Access, select Allow Guest Access.
5.
Enter the name of the folder that you created for public access, as shown below.
6.
Restart the BI Publisher application.
4-2
Chapter 4
Configuring BI Publisher for Secure Socket Layer (SSL) Communication
7.
Add the objects to the Guest folder that the guest users can access: folders,
reports, data models, Sub Templates and Style Templates.
Note:
The report must reference the data model that is stored in the guest folder.
Therefore, if you copy a report with its data model from another location, then
ensure that you open the report and reselect the data model so that the report
references the data model inside the guest folder.
Similarly, any references to Sub Templates or Style Templates must also be
updated.
8.
Grant access to the data sources used by data models in your Guest folder. See
Setting Up Data Sources for information on granting Guest access to a data
source.
Users who access BI Publisher see the Guest button on the log on page. Users can
click this button and view the reports in your chosen guest folder without presenting
credentials.
Configuring BI Publisher for Secure Socket Layer (SSL)
Communication
It is strongly recommended that you enable Secure Socket Layer (HTTPS) on the
middle tier hosting the Web services because the trusted username/password that is
passed can be intercepted.
This also pertains to Web services that are used for communication between BI
Publisher and Oracle BI Presentation Services.
Tasks for enabling SSL with BI Publisher:
•
Importing Certificates for Web Services Protected by SSL
•
Adding the Virtualize Property to the Identity Store Configuration
•
Updating the JDBC Connection String to the Oracle BI EE Data Source
•
Updating the JMS Configuration
•
Configuring the Delivery Manager
See Enabling End-to-End SSL in the Security Guide for Oracle Business Intelligence
Enterprise Edition.
Importing Certificates for Web Services Protected by SSL
If you make calls to Web services that are protected through Secure Sockets Layer
(SSL), then you must export the certificate from the Web server hosting the Web
service and import it into the Java keystore on the computer that is running BI
Publisher.
To import certificates for Web services:
4-3
Chapter 4
Configuring BI Publisher for Secure Socket Layer (SSL) Communication
1.
Navigate to the HTTPS site where the WSDL resides.
2.
Download the certificate by following the prompts; the prompts that you see vary
depending on the browser that you are using.
3.
Install the Certificate into your keystore using the Java keytool, as follows:
keytool -import -file <certfile> -alias <certalias> -keystore <keystore file>
4.
Restart the application server.
These steps should not be required if the server certificate is linked to some certificate
authority (such as Verisign). But if the Web service server is using a self-generated
certificate (for example, in a testing environment), then these steps are required.
Adding the Virtualize Property to the Identity Store Configuration
You must add the property "virtualize" to the Identity Store Configuration in Fusion
Middleware Control to enable SSL for BI Publisher.
To add the virtualize property:
1.
Log in to Fusion Middleware Control 12c:
https://<Host>/<SecureAdminPort>/em
2.
Select WebLogic Domain, Security, and then Security Provider Configuration.
3.
Expand the Security Store Provider segment.
4.
Expand the Identity Store Provider segment.
5.
Click Configure.
a.
Click Add (+) to add a new property.
b.
In the Add New Property dialog, enter
Property Name — virtualize
Value — true
6.
On the Identity Store Provide page, click OK.
4-4
Chapter 4
Configuring BI Publisher for Secure Socket Layer (SSL) Communication
7.
Confirm that the property is added to the jps-config.xml file:
a.
Open the jps-config.xml file located in
<DomainHome>/config/fmwconfig/jps-config.xml
b.
Ensure that the file contains the line:
<property name="virtualize" value="true"/>
Updating the JDBC Connection String to the Oracle BI EE Data
Source
For BI Publisher to connect to Oracle BI EE as a data source when SSL is enabled,
you must update the default connection string.
Follow the guidelines detailed in Setting Up a JDBC Connection to the Oracle BI
Server.
Updating the JMS Configuration
You update the Scheduler JMS configuration to use the SSL URL.
To update the JMS configuration:
1.
On the BI Publisher Administration page, under System Maintenance, click
Scheduler Configuration.
2.
Update the WebLogic JNDI URL to use SSL. For example,
4-5
Chapter 4
Enabling Secure Cookies
3.
Click Apply.
4.
Select the Scheduler Diagnostics tab.
5.
Verify that the connection passed diagnostics.
Configuring the Delivery Manager
If you want to use the default certificates built-in with BI Publisher, then no further
configuration is required.
SSL works with the default certificate if the server uses the certificate signed by a
trusted certificate authority such as Verisign.
If the user uses the SSL with a self-signed certificate, then the certificate information
must be entered in the Delivery Configuration page, as described in Configuring
Delivery Options. A self-signed certificate means that the certificate is signed by a nontrusted certificate authority (usually the user).
Enabling Secure Cookies
The cookie-secure flag tells the Web browser to only send the cookie back over an
HTTPS connection.
This ensures that the cookie is transmitted only on a secure channel. HTTPS must be
enabled for the URL exposed by the application.
To enable the cookie-secure flag, you must update the weblogic.xml within the
xmlpserver.war file (within the xmlpserver.ear) as follows:
1.
Locate the xmlpserver.ear file under ORACLE_HOME/bifoundation/jee/
2.
Unpack the xmlpserver.ear file.
3.
Unpack the xmlpserver.war file.
4.
Back up the WEB-INF/weblogic.xml file.
5.
Open the WEB-INF/weblogic.xmlfile.
6.
Add the following attributes to the <wls:session-descriptor>:
<wls:cookie-secure>true</wls:cookie-secure>
<wls:url-rewriting-enabled>false</wls:url-rewriting-enabled>
Example:
4-6
Chapter 4
Configuring Proxy Settings
<?xml version = '1.0' encoding = 'US-ASCII'?>
<wls:weblogic-web-app
xmlns:wls="http://xmlns.oracle.com/weblogic/weblogic-web-app"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd
http://xmlns.oracle.com/weblogic/weblogic-web-app
http://xmlns.oracle.com/weblogic/weblogic-web-app/1.2/weblogic-web-app.xsd">
<wls:session-descriptor>
<wls:cookie-path>/xmlpserver</wls:cookie-path>
<wls:cookie-secure>true</wls:cookie-secure>
<wls:url-rewriting-enabled>false</wls:url-rewriting-enabled>
</wls:session-descriptor>
<wls:context-root>xmlpserver</wls:context-root>
<wls:library-ref>
...
7.
Repack the xmlpserver.war file.
8.
Repack the xmlpserver.ear file.
9.
Go to your WebLogic Server console and update the bipublisher deployment.
Configuring Proxy Settings
To use external Web Services or HTTP data sources when the BI Publisher server is
configured behind a firewall or requires a proxy to access the internet, you must
configure Oracle WebLogic Server to allow the Web service requests and to be aware
of the proxy.
When configuring the proxy setting, you must also configure WebLogic Server to be
aware of any hosts that BI Publisher must connect to directly (not through the proxy)
for example, the Oracle BI Enterprise Edition host. Define the proxy host and the nonproxy hosts to WebLogic Server by setting the following parameters:
•
-Dhttp.proxyHost - specifies the proxy host. For example:
-Dhttp.proxyHost=www-proxy.example.com
•
-Dhttp.proxyPort - specifies the proxy host port. For example:
-Dhttp.proxyPort=80
•
-Dhttp.nonProxyHosts - specifies the hosts to connect to directly, not through the
proxy. Specify the list of hosts, each separated by a "|" character; a wildcard
character (*) can be used for matching. For example:
-Dhttp.nonProxyHosts="localhost|*.example1.com|*.example2.com
To set these proxy parameters and the Web service configuration for your WebLogic
Server add the following to the WebLogic setDomainEnv script as follows:
1.
Open the setDomainEnv script (.sh or .bat) in the MW_HOME/user_projects/
domains/DOMAIN_NAME/bin/directory.
2.
Enter the following parameters:
EXTRA_JAVA_PROPERTIES="-Dhttp.proxyHost=www-proxy.example.com Dhttp.proxyPort=80 -Dhttp.nonProxyHosts=localhost|*.mycompany.com|
*.mycorporation.com|*.otherhost.com ${EXTRA_JAVA_PROPERTIES}"
export EXTRA_JAVA_PROPERTIES
EXTRA_JAVA_PROPERTIES="-
4-7
Chapter 4
Restricting Embedding of BI Publisher in iframes
Djavax.xml.soap.MessageFactory=oracle.j2ee.ws.saaj.soap.MessageFactoryImpl
-Djavax.xml.soap.SOAPFactory=oracle.j2ee.ws.saaj.SOAPFactoryImpl Djavax.xml.soap.SOAPConnectionFactory=oracle.j2ee.ws.saaj.client.p2p.HttpSOAPConn
ectionFactory ${EXTRA_JAVA_PROPERTIES}"
export EXTRA_JAVA_PROPERTIES
where
www-proxy.example.com is an example proxy host
80 is the example proxy port
localhost|*.mycompany.com|*.mycorporation.com|*.otherhost.com are example non-
proxy hosts
Restricting Embedding of BI Publisher in iframes
You can prevent embedding of BI Publisher in iframes.
Configuring Embedding of BI Publisher
By default, users can embed BI Publisher in an iframe only if the iframe and BI
Publisher are in the same domain.
If you want to allow embedding of BI Publisher in an iframe belonging to another
domain or you want to completely restrict embedding of BI Publisher in an iframe,
provide appropriate values for the X_FRAME_OPTIONS and FRAME_ANCESTORS
properties in the xmlp-server-config.xml file.
Note:
If you set X_FRAME_OPTIONS to Deny and FRAME_ANCESTORS to none,
you can’t access the user interface of BI Publisher from other products that
can embed BI Publisher, including Oracle BI Enterprise Edition. If you specify
the values for both X_FRAME_OPTIONS and FRAME_ANCESTORS, the
value used depends on the browser. Make sure you provide similar values to
X_FRAME_OPTIONS and FRAME_ANCESTORS to ensure consistent
behavior across browsers.
X_FRAME_OPTIONS Values
Value
Specifies
False
Do not set the header option.
Deny
Do not allow users to embed BI Publisher in
iframes.
SameOrigin
Allow users to embed BI Publisher in iframes of
the same domain. This is the default.
Allow-From url
Allow users to embed BI Publisher only from the
domain specified in the url parameter.
See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options.
4-8
Chapter 4
Restricting Embedding of BI Publisher in iframes
FRAME_ANCESTORS Values
Value
Specifies
False
Do not set the header option.
none
Do not allow users to embed BI Publisher in
iframes.
self
Allow users to embed BI Publisher in iframes of
the same domain. This is the default.
url
Allow users to embed BI Publisher only from the
domain specified in the url parameter.
The URL can be repeated and can be specified
in more than one format.
See https://www.w3.org/TR/CSP2/#directive-frame-ancestors.
4-9
5
Integrating with Other Oracle Security
Models
This chapter describes BI Publisher support for security models of other Oracle
products including Oracle E-Business Suite security, Oracle Database security, and
Oracle Siebel CRM security.
It covers the following topics:
•
About Integrating with Other Oracle Security Models
•
Before You Begin: Create a Local Superuser
•
Integrating with Oracle BI Server Security
•
Integrating with Oracle E-Business Suite
•
Integrating with Oracle Database Security
•
Integrating with Oracle Siebel CRM Security
About Integrating with Other Oracle Security Models
This chapter describes how to integrate BI Publisher with other Oracle product security
models.
In most cases you must first define the BI Publisher functional roles in the other Oracle
product and then configure BI Publisher to use the other Oracle product security for
authorization. You can use one of the Oracle product authorization methods described
here in conjunction with a supported authentication method (SSO or LDAP) described
in Alternative Security Options.
For conceptual information regarding BI Publisher roles and permissions, see
Understanding BI Publisher Users, Roles, and Permissions.
Before You Begin: Create a Local Superuser
Before you implement any of these security models, first create a local superuser.
The local superuser credentials ensure that you can access the Administration pages
of Oracle BI Publisher in case of any unexpected failures in the configured security
settings.
To create a local superuser:
1.
On the Administration page, click Security Configuration.
2.
On the Security Configuration tab, under the Local Superuser region, select
Enable Local Superuser, as shown below.
5-1
Chapter 5
Integrating with Oracle BI Server Security
3.
Enter a name and password for your superuser.
4.
Restart BI Publisher to activate the superuser in the system.
Integrating with Oracle BI Server Security
If you have installed BI Publisher as part of the Oracle Business Intelligence Enterprise
Edition and you have configured Oracle BI Enterprise Edition to use legacy Oracle BI
Server authentication, then follow the procedures below to configure BI Publisher to
use BI Server security.
•
Configuring BI Publisher for Oracle BI Server Security
•
Adding Data Sources to BI Server Roles
Note:
The Oracle BI Server security option is for customers who want to use legacy
10g authentication. This section does not apply to you if you have configured
Oracle Fusion Middleware Security.
These procedures assume that you have performed the configuration required in the
BI Server. For information on configuring legacy Oracle BI security, see Security Guide
for Oracle Business Intelligence Enterprise Edition.
Configuring BI Publisher for Oracle BI Server Security
You configure BI Publisher for BI Server Security on the Administration page.
To configure BI Publisher for BI Server Security:
1.
Log in to BI Publisher with administrator credentials. Navigate to the BI Publisher
Administration page. On the Administration page, click Security Configuration.
5-2
Chapter 5
Integrating with Oracle E-Business Suite
Note:
To log in directly to the BI Publisher server, use the login URL with the /
xmlpserver suffix, for example: http://example.com:9502/xmlpserver
2.
In the Authorization region of the page, select Oracle BI Server from the Security
Model list. Provide the following connection information for the Oracle BI Server:
•
JDBC Connection String — Example: jdbc:oraclebi://host:port/
If you don’t know the connection string to the BI Server, then you can copy it
from data source connection page. From the Administration page, under Data
Sources, click JDBC Connection. Locate the Oracle BI EE server and copy
the connection string. If this has not been configured, then see Setting Up a
JDBC Connection to the Oracle BI Server.
•
3.
Database Driver Class — Example: oracle.bi.jdbc.AnaJdbcDriver
Click Apply. Restart the BI Publisher application for the security changes to take
effect.
Adding Data Sources to BI Server Roles
Add data sources to BI server roles from the Administration page.
To add data sources to BI server roles:
1.
Log in to Oracle Business Intelligence as an administrator.
2.
On the global header click Administration. On the Oracle BI Administration page,
click Manage BI Publisher.
3.
On the BI Publisher Administration page, click Roles and Permissions. The
groups to which you assigned the BI Publisher groups are displayed as available
roles.
4.
Find the group (role) to add data sources to and click Add Data Sources.
Alternatively, you can navigate to the data source and add the roles that require
access to the data source.
5.
Locate the appropriate data sources in the Available Data Sources list and use
the shuttle buttons to move the sources to the Allowed Data Sources list for the
role.
6.
Click Apply.
7.
Repeat the above steps for all roles that need access to report data sources.
Integrating with Oracle E-Business Suite
BI Publisher can leverage your E-Business Suite security to enable your users to log in
to BI Publisher using their E-Business Suite credentials. The BI Publisher security
integration recognizes the user's E-Business Suite responsibility and org_id
combinations.
When users log in, they are prompted to select a responsibility. Reports that users run
against the E-Business Suite data tables then filter the data based on their
5-3
Chapter 5
Integrating with Oracle E-Business Suite
responsibility and org_id combination. Users can switch responsibilities and reporting
organization while still logged in using the My Account dialog.
When you integrate with the E-Business Suite security, your E-Business Suite
responsibilities appear as roles in the BI Publisher security center. You can then add
BI Publisher catalog permissions and data access privileges to the imported roles/
responsibilities. See Understanding BI Publisher Users, Roles, and Permissions.
Follow these procedures to integrate BI Publisher with Oracle E-Business Suite:
•
Configuring BI Publisher to Use E-Business Suite Security
•
Adding Data Sources to the E-Business Suite Roles
•
Granting Catalog Permissions to the E-Business Suite Roles
Note:
In this release, users cannot access or execute reports that are stored on the
E-Business Suite instance. Reports must reside in the BI Publisher catalog.
The E-Business Suite data security is enforced when BI Publisher connects to
the E-Business Suite data tables to retrieve the report data.
Oracle BI Publisher relies on information stored in the DBC file to connect to the EBusiness Suite instance. Ensure that you can locate and have access to this file. The
DBC file is typically located under the $FND_SECURE directory.
Features of the Integration with E-Business Suite Security
When BI Publisher is integrated with E-Business Suite security, certain features are
enabled.
•
When users log in to BI Publisher using their E-Business Suite credentials, they
are prompted to choose a responsibility, as shown below.
5-4
Chapter 5
Integrating with Oracle E-Business Suite
•
Users can switch responsibilities or reporting organizations using the My Account
dialog.
•
The data source connection to the E-Business Suite instance is automatically
configured and available in the data model editor, as shown below.
Configuring BI Publisher to Use E-Business Suite Security
You configure BI Publisher for E-Business Suite Security on the Administration page.
To configure BI Publisher to use E-Business Suite security:
1.
2.
In the Oracle E-Business Suite, log in as a System Administrator and create the
following responsibilities to correspond to the BI Publisher functional roles:
•
XMLP_ADMIN — Serves as the administrator role for the BI Publisher server.
•
XMLP_DEVELOPER — Allows users to build reports in the system.
•
XMLP_SCHEDULER — Allows users to schedule reports.
•
XMLP_TEMPLATE_DESIGNER — Allows users to connect to the BI
Publisher server from the Template Builder and to upload and download
templates. Allows users to design layouts using the BI Publisher Layout Editor.
Add these new BI Publisher responsibilities to the appropriate users.
Note:
Ensure that you assign at least one user to the XMLP_ADMIN group.
3.
Log in to Oracle BI Publisher. On the Administration page, select Security
Configuration.
4.
In the Authorization region of the page, select Oracle E-Business Suite from the
Security Model list.
5-5
Chapter 5
Integrating with Oracle E-Business Suite
5.
Load the DBC file from the E-Business Suite instance. This is typically located
under the $FND_SECURE directory. If you do not have access to this file, then
contact your E-Business Suite system administrator. This file specifies how BI
Publisher should access the E-Business Suite instance.
6.
Click Apply. Restart BI Publisher for the security changes to take effect.
When you restart the system, the E-Business Suite responsibilities to which BI
Publisher roles have been assigned are visible as roles in the BI Publisher security
center.
Adding Data Sources to the E-Business Suite Roles
To view a report generated from a particular data source, a report consumer's role
must be granted access to the data source.
Similarly, to create a data model based on a particular data source, the report author's
role must be granted access to the data source.
To grant a role access to a data source:
1.
On the Administration tab, under Security Configuration, click Roles and
Permissions. The responsibilities that are assigned BI Publisher roles in the EBusiness Suite instance are displayed as available roles.
2.
Find the role to which you want to add data sources and click Add Data Sources.
The Add Data Sources page is displayed.
3.
Locate the appropriate data sources in the Available Data Sources list and use
the shuttle buttons to move the sources to the Allowed Data Sources list for the
role.
4.
Click Apply.
5.
Repeat for all roles that need access to report data sources.
Granting Catalog Permissions to the E-Business Suite Roles
For a role to access objects in a folder, you must grant the role permissions to the
catalog object.
You can grant permissions at the folder level, so that a role has the same access to
every object in a folder, or you can assign access individually to each object in a
folder.
See the following sections for more information:
•
Understanding BI Publisher Users, Roles, and Permissions
•
About Privileges to Use Functionality
•
About Catalog Permissions
•
How Functional Privileges and Permissions Work Together
To grant catalog permissions to E-Business Suite roles:
1.
In the catalog, navigate to a catalog object required for a role.
2.
Click the More link for the object and then click Permissions to open the
Permissions dialog.
5-6
Chapter 5
Integrating with Oracle Database Security
3.
Click Create to open the Add Roles dialog.
4.
Click Search to populate the list of Available Roles.
5.
Use the Move button to move the appropriate roles from the Available Roles list
to the Selected Roles list.
6.
Click OK.
7.
Enable the appropriate permissions for the role by selecting the check boxes.
8.
If you have selected a folder: To apply the selections to all items within a folder,
select Apply permissions to items within this folder.
Integrating with Oracle Database Security
BI Publisher offers integration with Oracle Database security to enable you to
administer the BI Publisher users with your Oracle Database users.
Follow these procedures to integrate BI Publisher with Oracle E-Business Suite:
•
Defining the BI Publisher Functional Roles in the Oracle Database
•
Adding Data Sources to Roles
•
Granting Catalog Permissions to Roles
Note:
For information on setting up Oracle Database security, see Oracle Database
Security Guide.
When you restart the server, the roles to which BI Publisher roles have been assigned
are visible as roles in the BI Publisher security center.
Defining the BI Publisher Functional Roles in the Oracle Database
You can create roles in the Oracle database that correspond to BI Publisher functional
roles.
To define BI Publisher functional roles in the Oracle database:
1.
2.
In the Oracle Database, create the following roles to correspond to the BI
Publisher functional roles:
•
XMLP_ADMIN — Serve as the administrator role for the BI Publisher server.
•
XMLP_DEVELOPER — Allows users to build reports in the system.
•
XMLP_SCHEDULER — Allows users to schedule reports.
•
XMLP_TEMPLATE_DESIGNER — Allows users to connect to the BI
Publisher server from the Template Builder and to upload and download
templates.
Assign these roles to the appropriate Database roles and users. You might also
want to create additional reporting roles that you can use when setting up your
report privileges on the BI Publisher side. For example, you might create a role
called "HUMAN_RESOURCES_MANAGER" that you can assign a Human
5-7
Chapter 5
Integrating with Oracle Database Security
Resources Folder of reports to. You can then assign that role to any user requiring
access to the Human Resources reports.
3.
Assign the XMLP_ADMIN role to a user with administration privileges, such as
SYSTEM.
4.
Log in to BI Publisher application with Administrator privileges. On the
Administration page, select Security Configuration.
5.
In the Authorization region of the page, select Oracle Database from the Security
Model list. Provide the following connection information:
•
JDBC Connection String — Example:
jdbc:oracle:thin:@mycompany.com:1521:orcl
•
Administrator Username and Administrator Password — Note the
following requirements for this user:
•
6.
–
The user must be granted the XMLP_ADMIN role
–
The user must have privileges to access data from the dba_users/_roles/
role_privs tables.
Database Driver Class — Example: oracle.jdbc.driver.OracleDriver
Click Apply. Restart BI Publisher for the security changes to take effect.
Adding Data Sources to Roles
To view a report generated from a particular data source, a report consumer's role
must be granted access to the data source.
Similarly, to create a data model based on a particular data source, the report author's
role must be granted access to the data source.
To grant a role access to a data source:
1.
On the Administration tab, under Security Configuration, click Roles and
Permissions.
2.
Find the role to which you want to add data sources and click Add Data Sources.
The Add Data Sources page is displayed.
3.
Locate the appropriate data sources in the Available Data Sources list and use
the shuttle buttons to move the sources to the Allowed Data Sources list for the
role.
4.
Click Apply.
5.
Repeat for all roles that need access to report data sources.
Granting Catalog Permissions to Roles
For a role to access objects in a folder, you must grant the role permissions to the
catalog object.
You can grant permissions at the folder level, so that a role has the same access to
every object in a folder, or you can assign access individually to each object in a
folder.
See the following sections for more information:
•
Understanding BI Publisher Users, Roles, and Permissions
5-8
Chapter 5
Integrating with Oracle Siebel CRM Security
•
About Privileges to Use Functionality
•
About Catalog Permissions
•
How Functional Privileges and Permissions Work Together
To grant catalog permissions to a role:
1.
In the catalog, navigate to a catalog object required for a role.
2.
Click the More link for the object and then click Permissions to open the
Permissions dialog.
3.
Click the Create icon to open the Add Roles dialog.
4.
Click Search to populate the list of Available Roles.
5.
Use the Move button to move the appropriate roles from the Available Roles list
to the Selected Roles list.
6.
Click OK.
7.
Enable the appropriate permissions for the role by selecting the check boxes.
8.
If you have selected a folder: To apply the selections to all items within a folder,
select Apply permissions to items within this folder.
Integrating with Oracle Siebel CRM Security
To configure BI Publisher to integrate with Siebel security, perform the tasks in the
following sections.
•
Setting Up BI Publisher Roles as Siebel CRM Responsibilities
•
Configuring BI Publisher to Use Siebel Security
•
Adding Data Sources to Roles
•
Granting Catalog Permissions to Roles
Setting Up BI Publisher Roles as Siebel CRM Responsibilities
After setting up BI Publisher Roles as Siebel CRM Responsibilities, assign these roles
to the appropriate users. You might also want to create additional reporting roles that
you can use when setting up your report privileges in the BI Publisher.
1.
Using Siebel Administrator credentials, navigate to Administration - Application,
and then Responsibilities.
2.
In the Responsibilities list, add a new record for each of the BI Publisher functional
roles:
3.
•
XMLP_ADMIN — Serves as the administrator role for the BI Publisher server.
•
XMLP_DEVELOPER — Allows users to build reports in the system.
•
XMLP_SCHEDULER — Allows users to schedule reports.
•
XMLP_TEMPLATE_DESIGNER — Allows users to connect to the BI
Publisher server from the Template Builder and to upload and download
templates and grants access to the layout editor.
Assign these roles to the appropriate users. You might also want to create
additional reporting roles that you can use when setting up your report privileges in
5-9
Chapter 5
Integrating with Oracle Siebel CRM Security
the BI Publisher. For example, you might create a role called
"EXECUTIVE_SALES" that you can assign a executive-level report folder. You
can then assign that role to any user requiring access to the Executive reports.
4.
Ensure to assign the XMLP_ADMIN role to a user with administration privileges.
Configuring BI Publisher to Use Siebel Security
You configure BI Publisher to use Siebel Security on the Administration page.
To configure BI Publisher to use Siebel Security:
1.
Log in to BI Publisher with Administrator privileges. On the Administration page,
select Security Configuration.
2.
In the Authorization region of the page, select Siebel Security from the Security
Model list. Provide the following connection information:
3.
•
Siebel Web Service Endpoint String
•
Administrator Username
•
Administrator Password
Click Apply. Restart BI Publisher for the security changes to take effect.
When you log back in to BI Publisher, the responsibilities to which you added the BI
Publisher functional roles are displayed on the Roles and Permissions page.
Adding Data Sources to Roles
To view a report generated from a particular data source, a report consumer's role
must be granted access to the data source.
Similarly, to create a data model based on a particular data source, the report author's
role must be granted access to the data source.
To grant a role access to a data source:
1.
On the Administration tab, under Security Configuration, click Roles and
Permissions.
2.
Find the role to which you want to add data sources and click Add Data Sources.
The Add Data Sources page is displayed.
3.
Locate the appropriate data sources in the Available Data Sources list and use
the shuttle buttons to move the sources to the Allowed Data Sources list for the
role.
4.
Click Apply.
5.
Repeat for all roles that need access to report data sources.
Granting Catalog Permissions to Roles
For a role to access objects in a folder, you must grant the role permissions to the
catalog object.
You can grant permissions at the folder level, so that a role has the same access to
every object in a folder, or you can assign access individually to each object in a
folder.
5-10
Chapter 5
Integrating with Oracle Siebel CRM Security
See the following sections for more information:
•
Understanding BI Publisher Users, Roles, and Permissions
•
About Privileges to Use Functionality
•
About Catalog Permissions
•
How Functional Privileges and Permissions Work Together
To grant catalog permissions to a role:
1.
In the catalog, navigate to a catalog object that is required for a role.
2.
Click the More link for the object and then click Permissions to open the
Permissions dialog.
3.
Click the Create icon to open the Add Roles dialog.
4.
Click Search to populate the list of Available Roles.
5.
Use the Move button to move the appropriate roles from the Available Roles list
to the Selected Roles list.
6.
Click OK.
7.
Enable the appropriate permissions for the role by selecting the check boxes.
8.
If you have selected a folder: To apply the selections to all items within a folder,
select Apply permissions to items within this folder.
5-11
6
Implementing a Digital Signature
This chapter describes how to implement a digital signature in PDF documents
generated by BI Publisher.
It covers the following topics:
•
Introduction
•
Prerequisites and Limitations
•
Obtaining Digital Certificates
•
Creating PFX Files
•
Implementing a Digital Signature
•
Running and Signing Reports with a Digital Signature
Introduction
BI Publisher supports digital signatures on PDF output documents.
Digital signatures enable you to verify the authenticity of the documents you send and
receive. Oracle BI Publisher can access your digital ID file from a central, secure
location and at runtime sign the PDF output with the digital ID. The digital signature
verifies the signer's identity and ensures that the document has not been altered after
it was signed.
For additional information, refer to the Verisign and Adobe websites.
Prerequisites and Limitations
Before you can implement digital signatures with Oracle BI Publisher output
documents, be aware of the following:
A digital ID obtained from a public certificate authority or from a private/internal
certificate authority (if for internal use only). You must copy the digital ID file to a
secure location of the file system on the server that is accessible by the BI Publisher
server.
Use of digital signatures with Oracle BI Publisher output documents has the following
limitations:
•
Only a single digital ID can be registered with BI Publisher.
•
Only reports submitted through BI Publisher's Schedule Report Job interface can
include the digital signature.
•
The digital signature is enabled at the report level; therefore, multiple templates
assigned to the same report share the digital signature properties.
6-1
Chapter 6
Obtaining Digital Certificates
Obtaining Digital Certificates
You can obtain a digital certificate either by purchasing one or by using the self-sign
method.
•
Purchase one from a certificate authority, such as Verisign, and save it to your
computer. This method is recommended because it is easier to verify (and
therefore trust) the authenticity of the certificate that you purchase. Next, use
Microsoft Internet Explorer 7 or later to create a PFX file based on the certificate
you purchased. See Creating PFX Files.
•
Create a self-signed certificate using a software program, such as Adobe Acrobat,
Adobe Reader, OpenSSL, or OSDT. This method is less preferred because
anyone can create a self-signed certificate. Therefore, it is more difficult to verify
and trust the authenticity of the certificate.
Typically, when you create a self-signed certificate using a software program, the
program saves the certificate as part of a PFX file. If this is the case, you do not
need to create another PFX file (as described in Creating PFX Files).
To create a self-signed certificate using Adobe Reader:
1.
Open Adobe Reader.
2.
From the Document menu, click Security Settings.
3.
Select Digital IDs on the left.
4.
On the toolbar, click Add ID.
5.
Follow the steps in the Add Digital ID wizard. For assistance, refer to the
documentation provided with Adobe Reader.
6.
When prompted, save your self-signed certificate as part of a PFX file to an
accessible location on your computer.
After you create your self-signed certificate as part of a PFX file, you can use the
PFX file to sign PDF documents by registering it with BI Publisher. See
Implementing a Digital Signature.
Creating PFX Files
If you obtained a digital certificate from a certificate authority, you can create a PFX file
using that certificate and Microsoft Internet Explorer 7 or later.
Note:
If you created a self-signed certificate using a software program such as
Adobe Reader, it is likely that the program created the certificate in a PFX file.
If this is the case, you don't have to create another PFX file. You can use the
one you have.
To create a PFX file with Microsoft Windows Explorer 7 or later:
1.
Ensure that your digital certificate is saved on your computer.
6-2
Chapter 6
Implementing a Digital Signature
2.
Open Microsoft Internet Explorer.
3.
From the Tools menu, click Internet Options and then click the Content tab.
4.
Click Certificates.
5.
In the Certificates dialog, click the tab that contains your digital certificate and then
click the certificate.
6.
Click Export.
7.
Follow the steps in the Certificate Export Wizard. For assistance, refer to the
documentation provided with Microsoft Internet Explorer.
8.
When prompted, select Use DER encoded binary X.509 as your export file
format.
9.
When prompted, save your certificate as part of a PFX file to an accessible
location on your computer.
After you create your PFX file, you can use it to sign PDF documents.
Implementing a Digital Signature
You can set up and sign your output PDF documents with a digital signature.
To implement a digital signature:
1.
Register the digital ID in the BI Publisher Administration page and specify the roles
that are authorized to sign documents, as described in Registering Your Digital
Signature ID and Assigning Authorized Roles.
2.
Specify the display field location, as described in Specifying the Signature Display
Field or Location.
3.
Enable Digital Signature for the report using the report properties.
4.
Log in to BI Publisher as a user with an authorized role and submit the report
through the BI Publisher scheduler, choosing PDF output. When the report
completes, it is signed with your digital ID in the specified location of the
document.
Registering Your Digital Signature ID and Assigning Authorized Roles
BI Publisher supports the identification of a single digital ID file.
To register a digital ID in the BI Publisher Administration page:
1.
On the Administration tab, under Security Center, click Digital Signature.
2.
On the Digital Signature subtab, enter the file path to the digital ID file and enter
the password for the digital ID.
3.
Enable the Roles that must have the authority to sign documents with this digital
ID. Use the shuttle buttons to move Available Roles to the Allowed Roles list.
4.
Click Apply. The figure below shows the Digital Signature subtab.
6-3
Chapter 6
Implementing a Digital Signature
Specifying the Signature Display Field or Location
You must specify the location for the digital signature to appear in the completed
document. The methods available depend on whether the template type is PDF or
RTF.
If the template is PDF, use one of the following options:
•
Specifying a Template Field in a PDF Template for the Digital Signature
•
Specifying the Location for the Digital Signature in the Report Properties
If the template is RTF, use the following option:
•
Specifying the Location for the Digital Signature in the Report Properties
Specifying a Template Field in a PDF Template for the Digital
Signature
Include a field in the PDF template for digital signatures.
See Adding or Designating a Field for a Digital Signature in Report Designer's Guide
for Oracle Business Intelligence Publisher for instructions on including a field in the
PDF template for the digital signature.
6-4
Chapter 6
Implementing a Digital Signature
Specifying the Location for the Digital Signature in the Report
Properties
When you specify a location in the document to place the digital signature, you can
either specify a general location (Top Left, Top Center, or Top Right) or you can
specify x and y coordinates in the document.
You can also specify the field height and width. This is done through properties on the
Runtime Configuration page. Therefore you do not need to alter the template to
include a digital signature.
To specify the location for the digital signature:
1.
In the catalog, navigate to the report.
2.
Click the Edit link for the report to open the report for editing.
3.
Click Properties and then click the Formatting tab.
4.
Scroll to the PDF Digital Signature group of properties.
5.
Set Enable Digital Signature to True.
6.
Specify the location in the document where you want the digital signature to
appear by setting the appropriate properties as follows (note that the signature is
inserted on the first page of the document only):
•
Existing signature field name — Does not apply to this method.
•
Signature field location — Provides a list containing the following values:
Top Left, Top Center, Top Right
Select one of these general locations and BI Publisher places the digital
signature in the output document sized and positioned appropriately.
If you set this property, then do not enter X and Y coordinates or width and
height properties.
•
Signature field X coordinate — Using the left edge of the document as the
zero point of the X axis, enter the position in points to place the digital
signature from the left.
For example, to place the digital signature horizontally in the middle of an 8.5
inch by 11 inch document (that is, 612 points in width and 792 points in
height), enter 306.
•
Signature field Y coordinate — Using the bottom edge of the document as
the zero point of the Y axis, enter the position in points to place digital
signature from the bottom.
For example, to place the digital signature vertically in the middle of an 8.5
inch by 11 inch document (that is, 612 points in width and 792 points in
height), enter 396.
•
Signature field width — Enter in points the desired width of the inserted
digital signature field. This applies only if you are setting the X and Y
coordinates.
•
Signature field height — Enter in points the desired height of the inserted
digital signature field. This applies only if you are setting the X and Y
coordinates.
6-5
Chapter 6
Running and Signing Reports with a Digital Signature
The figure below shows a report that is configured to place the digital signature at
specific x and y coordinates in the document.
Running and Signing Reports with a Digital Signature
Users assigned a role with the digital signature privilege can attach the digital
signature to their generated reports configured to include the digital signature. The
digital signature can be inserted only on scheduled reports.
To sign reports with a digital signature:
1.
Log in to BI Publisher as a user with a role granted digital signature privileges.
2.
In the catalog, navigate to the report that has been enabled for digital signature,
and click Schedule.
3.
Complete the fields on the Schedule Report Job page, select PDF output, and
then submit the job.
The completed PDF displays the digital signature.
6-6
7
Configuring the Scheduler
This chapter describes the features, architecture, diagnostics, and configuration of the
BI Publisher scheduler.
It covers the following topics:
•
Understanding the BI Publisher Scheduler
•
Set Up Considerations
•
About the Scheduler Configuration
•
Configuring Processors and Processor Threads
•
Adding Managed Servers
•
Scheduler Diagnostics
Understanding the BI Publisher Scheduler
The updated architecture of the 11g BI Publisher Scheduler uses the Java Messaging
Service (JMS) queue technology.
This architecture enables you to add multiple BI Publisher servers to a cluster and
then dedicate each server to a particular function: report generation, document
generation, or specific delivery channels.
Architecture
The architecture of the BI Publisher Scheduler uses JMS queues and topics to provide
a highly scalable, highly performing and robust report scheduling and delivery system.
The figure below displays the scheduler architecture.
7-1
Chapter 7
Understanding the BI Publisher Scheduler
The following list describes the tasks performed by the scheduler when a job is
submitted:
1.
Submit Job
•
2.
Job Processor
•
3.
When quartz trigger is fired, puts job information in Scheduler job queue
Bursting Engine / Batch Job Process
•
•
4.
Stores job information and triggers in Quartz tables
Bursting Engine Listener
–
Takes the scheduled job information from the queue
–
Extracts data from data source
–
Splits data according to bursting split by definition
–
Stores data temporarily in temp folder
–
Puts report metadata into Report Queue
Batch Job Process
–
Takes the scheduled job information from the queue
–
Extracts data from data source
–
Stores data temporarily in temp folder
–
Puts report metadata into Report Queue
FO Report Processor
•
Listens to Report Q
7-2
Chapter 7
Understanding the BI Publisher Scheduler
5.
6.
•
Generates report based on metadata
•
Stores report in shared TEMP directory
•
Puts report delivery information in Delivery Queue
Delivery (E-mail, File, FTP) Processors
•
Listen to Delivery queue
•
Call delivery API to deliver to different channels
BI Publisher (BIP) System Topic
The BIP System Topic publishes the runtime status and health of the scheduling
engine. The topic publishes the status of all instances, the thread status of
messages in the JMS queues, the status of all scheduler configurations such as
database configuration, JNDI configuration of JMS queues and so on.
About Clustering
BI Publisher clustering support enables you to add server instances on demand to
handle processing and delivery load.
The figure below illustrates clustering in an Oracle WebLogic Server. Note that the
report repository and the scheduler database are shared across the multiple instances;
also, the JMS queues for scheduling and JMS topic for publishing diagnostic
information are shared across the server by registering JMS queues and topics
through JNDI services.
Each managed server instance points to the same report repository. In each managed
server instance all the processes (Job Processor, Report Processor, E-mail Processor,
FTP Processor, Fax Processor, File Processor, Print Processor, and Web Dav
Processor) are configured. Therefore the moment a server instance pointing to the
7-3
Chapter 7
Set Up Considerations
same repository is deployed, it is added to the cluster and all the processors in this
instance are ready to run.
You can select the process to enable on any server instance, thereby using the
resources optimally. Moreover, if there is a demand to process heavier jobs you can
add more instances for report processing. Similarly, if e-mail delivery is the most
preferred delivery channel, then more instances can be added to scale up e-mail
delivery.
See High Availability Guide.
How Failover Works
BI Publisher provides a robust failover mechanism so that no report fails to deliver due
to server unavailability.
Achieve this by balancing each process of the Scheduler using two or more nodes in a
cluster thereby ensuring that a failure of any node must be backed up by the second
node without any loss of data. For example, by enabling the Job Processor in two
nodes, if one node fails, then the second node can process the jobs.
Note:
If a node goes down, the other nodes continue to service the queue. However,
if a report job is in one of the following stages of execution: data retrieval, data
formatting, or report delivery, the job is marked as failed, and must be
manually resubmitted.
Set Up Considerations
There are certain topics you should consider before setting up the scheduler.
•
Table Space Requirements
•
Choosing JNDI or JDBC Connection
•
Supported JMS Providers
Table Space Requirements
The database containing the Oracle Business Intelligence Scheduler database tables
requires minimum disk space.
Minimum disk space requirements include:
•
500MB on Oracle and Microsoft SQL Server databases for standalone and
Business Intelligence applications and deployments.
•
500MB on IBM DB2 databases for standalone deployments.
For report storage, you must calculate the appropriate amount of space based on your
company's usage. If you generate and archive multiple large reports, for example if
your company generates an average of 2GB total file size of reports per month, and
you also store the XML data for a period of one year, then the requirement will be (2
GB x 2 x 12 = 48 GB) on disk. Note that the size of the BLOB and CLOB may not be
7-4
Chapter 7
About the Scheduler Configuration
the same in the database as in the file system, but this calculation can provide
approximate requirements.
Choosing JNDI or JDBC Connection
By default, the BI Platform installer configures the WebLogic JNDI connection URL.
JDBC is not recommended for production use. JDBC should only be used for low
volume local testing.
Supported JMS Providers
When you install BI Publisher, the scheduler is automatically configured to use
WebLogic JMS.
To configure BI Publisher to use ActiveMQ instead, see Configuring BI Publisher for
ActiveMQ.
About the Scheduler Configuration
After you install BI Publisher using the BI Platform Installer and start the servers, the
BI Publisher scheduler starts running and certain configurations occur.
•
The scheduler schema is installed to the database by the Repository Creation
Utility as a preinstall step.
•
JMS is configured in your server for BI Publisher.
•
The WebLogic JNDI URL is configured.
•
Default threads per processor is set to 5.
See Installing and Configuring Oracle Business Intelligence.
You can see this configuration in the Scheduler Configuration page: From the
Administration page, under System Maintenance, click Scheduler Configuration. The
figure below shows the Database Connection and JMS Configuration regions of the
Scheduler Configuration page.
7-5
Chapter 7
Configuring Processors and Processor Threads
Configuring the Shared Directory
The Shared Directory is used to temporarily store data and files used by the scheduler
while jobs are executing.
After a job completes, the temporary data for the job is deleted. If the BI Publisher
scheduler is configured to run on different nodes or machines, you must define this
directory. The directory is used to exchange data and document information among all
the BI Publisher nodes and therefore must be accessible by all BI Publisher nodes.
The size of the directory depends on the total size of the job data, output documents,
and the number of concurrent jobs. The directory should be big enough to hold all the
XML data and documents for all the parallel running jobs. If BI Publisher runs on
different machines while this directory is not configured, the scheduler may fail.
If BI Publisher runs on a single machine, defining a shared directory is optional. BI
Publisher uses the application server's temporary directory to store this data.
Configuring Processors and Processor Threads
For each cluster instance that you have configured, a processor configuration table is
displayed. Use the tables to enable and disable processors and specify threads for
each processor.
The default number of threads for each processor is set by the Threads per JMS
Processor property under JMS Configuration, as shown in the figure below. Edit the
threads for a specific processor in the Cluster Instances region by updating the
Number Threads setting. Note that processors that use the default setting show no
entry in the table. Enter a Number Threads value only to set a thread count for a
particular processor to differ from the default.
7-6
Chapter 7
Adding Managed Servers
The optimum number of threads per processor depends on the requirements of the
system. You can use the Scheduler Diagnostics page to help in assessing load in the
system. See Scheduler Diagnostics.
To add managed servers to the system, see Adding Managed Servers.
Adding Managed Servers
Add managed servers in the Oracle WebLogic Administration Console and then
configure the cluster instances in the BI Publisher Administration page.
•
Adding a Managed Server
•
Configuring the Processors in BI Publisher
Adding a Managed Server
You manage servers in the Oracle WebLogic Administration Console.
See Oracle WebLogic Server Administration Console Online Help and Administering
Oracle Fusion Middleware.
To add a managed server:
1.
Access the Oracle WebLogic Administration Console.
2.
Click Lock & Edit.
3.
Under Domain Structure, expand Environment and click Servers.
4.
On the Servers table, click New.
5.
On the Create a New Server: Server Properties page:
•
Enter the name of the server in the Name field.
•
In Listen Port, enter the port number from which you want to access the server
instance.
•
Select Yes, make this server a member of an existing cluster.
•
Select the bi_cluster from the list.
•
Click Next.
7-7
Chapter 7
Adding Managed Servers
6.
Review the configuration options that you have chosen.
7.
Click Finish.
The new server displays in the Servers table, as shown in the figure below.
8.
Click the server name to open the Settings page.
9.
Select a Machine for the new server.
10. Click Save.
11. Click Activate Changes.
12. Start the new server.
Configuring the Processors in BI Publisher
After the new managed server has been started, the set of processors for that server
displays in BI Publisher.
7-8
Chapter 7
Setting Job Priority
You can now configure the threads appropriately for your system load.
Setting Job Priority
This topic describes setting job priority and handling critical jobs.
In BI Publisher releases earlier than 12.2.1.3, critical jobs, non-critical jobs, and ondemand queries competed for resources. Sometimes, the critical jobs were delayed or
the jobs failed to complete for the following reasons:
•
Out of memory
•
External system unavailability
•
First in, first out (FIFO) ordering for all jobs
BI Publisher 12.2.1.3 offers:
•
Priority setting for a report
•
Recovery of interrupted jobs
7-9
Chapter 7
Scheduler Diagnostics
Job Priority
In the Report Properties page, you can assign critical, normal, or low priority for a
report. BI Publisher sets the JMS Priority to sort the scheduled report jobs based on
the priority, and enables the high priority report jobs to run before the non-critical jobs.
See Setting Report Properties in Report Designer's Guide for Oracle Business
Intelligence Publisher.
In the Report Job History page, you can easily identify the critical jobs and view the
status of each job. See Viewing Report Job History and Saved Output in User's Guide
for Oracle Business Intelligence Publisher.
Job Recovery
When the Oracle BI managed server or BI Publisher goes down, a long running job
might get interrupted. BI Publisher resumes all the interrupted jobs when the Oracle BI
managed server restarts. When a job is recovered, BI Publisher resumes the job from
a logical point that was completed before the interruption and uses the data that was
fetched by the job before interruption.
If BI Publisher can’t resume an interrupted job, it reruns that job as a new job. BI
Publisher can’t recover a job that failed before Oracle BI Server restarts. In this case,
you might have to manually resubmit the failed job.
The Report Job History page displays the recovery details when you hover on the
status icon of a job.
Scheduler Diagnostics
The Scheduler diagnostics page provides the runtime status of the scheduler. It
provides status of its JMS configuration, JMS queues, Cluster instance status,
Scheduler Database status, Toplink status, and Scheduler (Quartz) status.
The Diagnostics page displays how many scheduled report requests have been
received by the JMS queues, how many of them have failed and how many are still
running. The JMS status can be viewed at the cluster-instance level enabling you to
decide whether to add more instances to scale up by one or more of these JMS
processors.
For example, if there are too many requests queued up for the e-mail processor in one
instance, you can consider adding another instance and enabling it to handle e-mail
processing. Similarly, if there are very large reports being processed and showing in
the Report Process queue in running status, then you can add another instance to
scale up the Report Process capability.
Also, the Scheduler Diagnostics page reflects the status of each component to show if
any component is down. You can see the connection string or JNDI name to the
database, which cluster instance associates to which managed server instance,
Toplink connection pool configuration, and so on.
If an instance shows a failed status, then you can recover the instance and with the
failover mechanism of the JMS set up in the cluster, no jobs submitted are lost. When
the server instance is brought back, it is immediately available in the cluster for
service. The instance removal and addition reflects dynamically on the diagnostic
page.
7-10
Chapter 7
Scheduler Diagnostics
When an instance is added to the cluster, the Scheduler Diagnostics page immediately
recognizes the new instance and displays the status of the new instances and all the
threads running on that instance. This provides a powerful monitoring capability to the
administrator to trace and resolve issues in any instance or any component of the
scheduler.
The Scheduler Diagnostics page provides information on the following components:
•
JMS
•
Cluster
•
Database
•
Scheduler Engine
The JMS section provides information on the following:
•
•
JMS Cluster Config: This section provides configuration information for JMS
setup:
–
Provider type (Weblogic / ActiveMQ)
–
WebLogic version
–
WebLogic JNDI Factory
–
JNDI URL for JMS
–
Queue names
–
Temporary directory
JMS Runtime: This provides runtime status of all JMS queues and topics, as
shown in the table below.
The Cluster section provides details on the cluster instance, as shown in the figure
below. Use this information to understand the load on each processor.
7-11
Chapter 7
Scheduler Diagnostics
•
JMS instance config
•
JMS Wrapper
•
JMS Client - System — Provides status of the BIP System topic. The scheduler
diagnostic page is a subscriber to this topic.
•
JMS Client_producer — Not used in this release.
•
JMS Client_schedule — Provides status of the job processor and report
processor, each processor showing number of active threads, number of
messages received, number of messages failed, and number of messages
running.
•
JMS Client_delivery — Provides status of different delivery processors as
listeners, each delivery processor showing number of active threads, number of
messages received, number of messages failed, and number of messages
running.
The Database section provides information on these components, as shown in the
figure below.
•
Database Config — Connection type, JNDI Name, or connection string
•
Toplink Config — Connection pooling, logging level
•
Database Schema
7-12
Chapter 7
Scheduler Diagnostics
The Quartz section provides information on these components, as shown in the figure
below.
•
Quartz Configuration
•
Quartz Initialization
Resolving Quartz Configuration Errors
The following is a common Quartz configuration error in the Scheduler Diagnostics
page:
Error Description and Resolution
During the BI Publisher start up (when the WebLogic Managed server or Admin server
are started) if the JNDI data source configured as jdbc/bip_datasource is unavailable,
then the Quartz initialization will fail. The Scheduler Diagnostics page displays an error
for Quartz Configuration.
If this occurs, perform the following:
1.
Verify that the data source configured asjdbc/bip_datasourceis available. On the
Scheduler Configuration page, click Test Connection to ensure the connection is
working.
2.
On the Scheduler Diagnostics page, locate the "Database Schema" diagnostics
item and ensure it passed.
3.
Go back to the Scheduler Configuration page and change the Scheduler
Selection from "Quartz" to "None" and click Apply. Now change it back to
"Quartz" and click Apply again.
4.
On the Scheduler Diagnostics page, verify that the Quartz error has cleared.
7-13
8
Configuring System Maintenance
Properties
This chapter describes how to configure BI Publisher server properties such as
caching specifications, monitoring and auditing, and catalog properties.
It covers the following topics:
•
Navigating to the System Maintenance Properties
•
Configuring the Catalog
•
Setting General Properties
•
Setting Server Caching Specifications
•
Setting Retry Properties for Database Failover
•
Enabling Monitor and Audit
•
Setting Report Viewer Properties
•
Clearing Report Objects from the Server Cache
•
Purging Job Diagnostics Log
Navigating to the System Maintenance Properties
You navigate to the System Maintenance properties from the Administration page.
1.
On the Oracle Business Intelligence header, click Administration.
If you are using Oracle Business Intelligence Enterprise Edition, next click Manage
BI Publisher.
2.
On the BI Publisher Administration page, under System Maintenance, click Server
Configuration.
The figure below shows the system properties.
8-1
Chapter 8
Configuring the Catalog
Configuring the Catalog
You can configure the catalog location by changing the SDD (Singleton Data
Directory) path. The default SDD path is DOMAIN_HOME/bidata.
In Oracle Business Intelligence 12c, for metadata and other cross-cluster files, there is
one SDD (Singleton Data Directory) for each domain. You can change the SDD path
in the DOMAIN_HOME/config/fmwconfig/bienv/core/bi-environment.xml file. See
Changing the Singleton Data Directory (SDD) in System Administrator's Guide for
Oracle Business Intelligence Enterprise Edition.
BI Publisher supports:
•
Oracle BI Publisher file system catalog for installations of BI Publisher that are not
integrated with Oracle Business Intelligence Enterprise Edition. When using file
systems such as NFS, Windows, or NAS for the repository, ensure that the file
system is secured.
•
Shared Oracle BI EE Presentation catalog for installations of BI Publisher
integrated with the Oracle Business Intelligence Enterprise Edition.
Configuring the BI Search Fields
If you have configured Oracle Business Intelligence with Oracle Secure Enterprise
Search (Oracle SES), configure certain fields to enable the full text search for BI
Publisher objects.
Prerequisites
Before configuring the fields in BI Publisher, you must first perform the following:
1.
Set up Oracle Secure Enterprise Search (Oracle SES).
8-2
Chapter 8
Setting General Properties
2.
Integrate Oracle SES with Oracle Business Intelligence Presentation Services.
For completing the prerequisites and configuring for full-text catalog search, see
System Administrator's Guide for Oracle Business Intelligence Enterprise Edition.
Enter the following fields in BI Publisher:
•
BI Search URL - enter the basic URL for Oracle Business Intelligence, adding
the search context name; takes the format:
http://computer_name:port/bisearch
•
BI Search URL Suffix — this field defaults to "rest/BISearchQueryService/
search". Do not edit this field.
•
BI Search Group name — enter the name of the search group that you created in
Oracle SES, for example: bisearch_ws
•
BI Search Timeout (millisecond) — enter the maximum number of milliseconds
that Oracle BI Publisher waits for a response to return with search results. This
field defaults to 22000.
The figure below shows the BI search fields.
Setting General Properties
The general properties region includes the following settings:
•
System Temporary Directory
•
Report Scalable Threshold
System Temporary Directory
This section includes the topics about setting a system temporary directory.
Topics include:
•
About Temporary Files
•
Setting the System Temporary Directory
•
Sizing the System Temporary Directory
About Temporary Files
BI Publisher creates both temporary and cache files.
Temporary files:
•
Temporary files created by the formatting engines (FO processor, PDF Form
Processor, PDF generators and so on)
8-3
Chapter 8
Setting General Properties
•
Data Files
These files are removed after the reports generate successfully.
Dynamic image files for HTML output:
•
Dynamic charts
•
Embedded images in RTF templates
Cache files:
•
Data cache
•
LOV (List of Values) cache
•
Document Cache
•
XSL Cache from RTF templates
Setting the System Temporary Directory
If you do not specify a temporary directory here, temporary files and dynamic image
files are generated under {bip_deployment_directory}/xdo/tmp. Cache files are
generated under {bip_deployment_directory}/xdo/cache.
When you configure a System Temporary Directory using this field, for example: "/
disk1/BIP_Temp", the BI Publisher server automatically creates the following
directories:
•
/disk1/BIP_Temp/xdo
•
/disk1/BIP_Temp/xdo/tmp
•
/disk1/BIP_Temp/xdo/cache
Temporary files are generated under /disk1/BIP_Temp/xdo/tmp.
Cache files are generated under /disk1/BIP_Temp/xdo/cache.
Dynamic image files are still created in the {bip_deployment_directory}/xdo/tmp
directory and are not affected by this configuration.
Whenever the BI Publisher server is restarted, any files under /disk1/BIP_Temp/xdo
are removed.
Note:
When using the BI Publisher web services uploadReportDataChunk() or
downloadReportDataChunk() in a clustered environment, you must set the
System Temporary Directory to be a shared directory accessible to all
servers within the cluster.
You must enter the absolute path to the directory. For example, the directory
can exist under ${xdo.server.config.dir}/temp but you must enter the
absolute path, such as /net/subfoldera/scratch/subfolderb/12ccat/temp
Repeat this procedure for all servers in the cluster, entering the same value for
System Temporary Directory.
8-4
Chapter 8
Setting Server Caching Specifications
Sizing the System Temporary Directory
Sizing requirements depend on how large the generated data files and reports are,
how many reports enabled cache, and the number of concurrent users.
If you must process 1 GB of data and then to generate a report that is 1 GB, then the
temp disk should have more than 2 GB of disk space for a single report run. If you
require ten concurrent report runs of similarly sized reports, then more than 20 GB of
disk space is required. In addition, if you must cache the data and reports for these ten
users, you need additional 20 GB of disk space. Note that cache is per user.
Report Scalable Threshold
This property specifies the threshold at which data is cached on the disk.
When the data volume is large, caching the data saves memory, but results in slower
processing. Enter a value in bytes. The default and general recommendation for this
property is 1000000 (1 megabyte).
Setting Server Caching Specifications
When BI Publisher processes a report, the data and the report document are stored in
cache.
Each item creates a separate cache file. Set the following properties to configure the
size and expiration of this cache:
•
Cache Expiration — Enter the expiration period for the cache in minutes. The
default is 30.
•
Cache Size Limit — Enter the maximum number of cached items to maintain
regardless of the size of these items. The default is 1000.
When BI Publisher processes a report it stores the report definition in memory so that
for subsequent requests for the same report the report definition can be retrieved from
memory rather than from disk. Set the following property to configure this cache:
•
Maximum Cached Report Definitions — Enter the maximum number of report
definitions to maintain in cache. The default is 50. You can specify the timeout for
report definitions in the "Cache Expiration" box. If you do not specify the
expiration, the default timeout is 20 minutes.
To manually purge this cache, use the Clear Object Cache button on the Manage
Cache tab. See Clearing Report Objects from the Server Cache.
Note:
Report-specific caching of data sets can be set as a report property. See
Configuring Report Properties in Report Designer's Guide for Oracle Business
Intelligence Publisher.
8-5
Chapter 8
Setting Retry Properties for Database Failover
Setting Retry Properties for Database Failover
If BI Publisher fails to connect to a data source through the defined JDBC or JNDI
connection, then these properties control the number of retries that are attempted
before switching to the backup connection for the database.
•
Number of Retries
Default value is 6. Enter the number of times to attempt to make a connection
before switching to the backup database.
•
Retry Interval (seconds)
Default value is 10 seconds. Enter the number of seconds to wait before retrying
the connection.
Enabling Monitor and Audit
This setting enables user auditing and monitoring in BI Publisher. Performance
monitoring enables you to monitor the performance of queries, reports and document
generation and to analyze the provided details.
Selecting the Enable Monitor and Audit check box on the Server Configuration
page is the first step required for enabling performance monitoring and user auditing in
your system.
For the complete steps, see About Performance Monitoring and User Auditing.
Setting Report Viewer Properties
The Report Viewer Configuration tab enables you to set the Show Apply
Buttonreport viewer property .
When set to True, reports with parameter options display the Apply button in the
report viewer. When a user changes the parameter values, he must click Apply to
render the report with the new values.
When set to False, the report viewer does not display the Apply button. Instead, when
a user enters a new parameter value, BI Publisher automatically renders the report
after the new value is selected or entered.
This property can also be set at the report level to override the system setting. For
information on setting the property at the report level, see Configuring Parameter
Settings for the Report in Report Designer's Guide for Oracle Business Intelligence
Publisher.
Clearing Report Objects from the Server Cache
Use the Manage Cache page to clear the server cache.
The server cache (Setting Server Caching Specifications) stores report definitions,
report data, and report output documents. If you need to manually purge this cache
(for example, after patching) use the Manage Cache page.
To manually clear this cache before the expiration:
8-6
Chapter 8
Purging Job Diagnostics Log
1.
From the BI Publisher Administration page, click Manage Cache.
2.
On the Manage Cache page, click Clear Object Cache.
Purging Job Diagnostics Log
Use the Manage Job Diagnostics Log page to purge old job diagnostics log.
The retention period of job diagnostic log is set to 30 days, by default. If you frequently
enable diagnostic logs, these diagnostic logs might consume space in the database,
and you might need to periodically free the space consumed by the old diagnostic
logs.
You can manually purge the diagnostic logs older than the retention period by
performing the following steps.
1.
In Administration > System Maintenance page, click Manage Job Diagnostics
Log.
2.
Click Purge log beyond retention period.
8-7
9
Setting Up Data Sources
This chapter describes how to set up data sources for BI Publisher including JDBC
and JNDI connections, LDAP server connections, OLAP data sources, and file data
sources.
It covers the following topics:
•
Overview of Setting Up Data Sources
•
Setting Up a JDBC Connection to the Data Source
•
Setting Up a Database Connection Using a JNDI Connection Pool
•
Setting Up a Connection to an LDAP Server Data Source
•
Setting Up a Connection to an OLAP Data Source
•
Setting Up a Connection to a File Data Source
•
Setting Up a Connection to a Web Service
•
Setting Up a Connection to a HTTP XML Feed
•
Viewing or Updating a Data Source
Overview of Setting Up Data Sources
BI Publisher supports a variety of data sources. The data can come from a database,
a HTTP XML feed, a Web Service, an Oracle BI Analysis, an OLAP cube, a LDAP
server, or a previously generated XML file or Microsoft Excel file.
About Private Data Source Connections
Private connections for OLAP, JDBC, Web Service, and HTTP data sources are
supported in BI Publisher and can be created by users with data model creation
privileges.
When a user creates a private data source connection, it displays only for that user in
the data model editor data source menus. For example, a user creates a private data
source connection called "my datasource." When the user creates a data set, the
private data source connection displays in the Data Source selection menu as shown
in the figure below.
9-1
Chapter 9
Overview of Setting Up Data Sources
Administrators have access to the private data source connections created by users.
All private data source connections are displayed to Administrators when they view the
list of OLAP, JDBC, Web Service, and HTTP data sources from the BI Publisher
Administration page.
Private data source connections are distinguished by an Allowed User value on the
Data Source Administration page as shown in the figure below. Administrators can
extend access to other users to a private data source connection by assigning
additional user roles to it.
For more information on assigning roles to data sources, see Granting Access to Data
Sources Using the Security Region.
For more information about creating private data source connections, see Managing
Private Data Sources in Data Modeling Guide for Oracle Business Intelligence
Publisher.
9-2
Chapter 9
Overview of Setting Up Data Sources
Granting Access to Data Sources Using the Security Region
When you set up data sources, you can also define security for the data source by
selecting which user roles can access the data source.
You must grant access to users for the following:
•
A report consumer must have access to the data source to view reports that
retrieve data from the data source
•
A report designer must have access to the data source to create or edit a data
model against the data source
By default, a role with administrator privileges can access all data sources.
The configuration page for the data source includes a Security region that lists all the
available roles. You can grant roles access from this page, or you can also assign the
data sources to roles from the roles and permissions page.
See Configuring Users, Roles, and Data Access for information.
If this data source must be used in guest reports, then you must also enable guest
access here. For more information about guest access see Enabling a Guest User.
The figure below shows the Security region of the data source configuration page.
About Proxy Authentication
BI Publisher supports proxy authentication for connections to various data sources
Supported data sources include:
•
Oracle 10g database
•
Oracle 11g database
•
Oracle BI Server
For direct data source connections through JDBC and connections through a JNDI
connection pool, BI Publisher enables you to select "Use Proxy Authentication". When
you select Use Proxy Authentication, BI Publisher passes the user name of the
9-3
Chapter 9
Overview of Setting Up Data Sources
individual user (as logged into BI Publisher) to the data source and thus preserves the
client identity and privileges when the BI Publisher server connects to the data source.
Note:
Enabling this feature requires additional setup on the database. The database
must have Virtual Private Database (VPD) enabled for row-level security.
For more information on Proxy Authentication in Oracle databases, see Oracle
Database Security Guide.
For connections to the Oracle BI Server, Proxy Authentication is required. In this case,
proxy authentication is handled by the Oracle BI Server, therefore the underlying
database can be any database that is supported by the Oracle BI Server.
Choosing JDBC or JNDI Connection Type
In general, a JNDI connection pool is recommended because it provides the most
efficient use of your resources.
For example, if a report contains chained parameters, then each time the report is
executed, the parameters initiate to open a database session every time.
About Backup Databases
When you configure a JDBC connection to a database, you can also configure a
backup database.
A backup database can be used in two ways:
•
As a true backup when the connection to the primary database is unavailable
•
As the reporting database for the primary. To improve performance you can
configure your report data models to execute against the backup database only.
To use the backup database in either of these ways, you must also configure the
report data model to use it.
See Setting Data Model Properties in Data Modeling Guide for Oracle Business
Intelligence Publisher for configuring a report data model to use the backup data
source.
About Pre Process Functions and Post Process Functions
You can define PL/SQL functions for BI Publisher to execute when a connection to a
JDBC data source is created (preprocess function) or closed (postprocess function).
The function must return a Boolean value. This feature is supported for Oracle
databases only.
These two fields enable the administrator to set a user's context attributes before a
connection is made to a database and then to dismiss the attributes after the
connection is broken by the extraction engine.
9-4
Chapter 9
Setting Up a JDBC Connection to the Data Source
The system variable :xdo_user_name can be used as a bind variable to pass the login
username to the PL/SQL function calls. Setting the login user context in this way
enables you to secure data at the data source level (rather than at the SQL query
level).
For example, assume you have defined the following sample function:
FUNCTION set_per_process_username (username_in IN VARCHAR2)
RETURN BOOLEAN IS
BEGIN
SETUSERCONTEXT(username_in);
return TRUE;
END set_per_process_username
To call this function every time a connection is made to the database, enter the
following in the Pre Process Function field:
set_per_process_username(:xdo_user_name)
Another sample usage might be to insert a row to the LOGTAB table every time a user
connects or disconnects:
CREATE OR REPLACE FUNCTION BIP_LOG (user_name_in IN VARCHAR2, smode IN VARCHAR2)
RETURN BOOLEAN AS
BEGIN
INSERT INTO LOGTAB VALUES(user_name_in, sysdate,smode);
RETURN true;
END BIP_LOG;
In the Pre Process Function field enter: BIP_LOG(:xdo_user_name)
As a new connection is made to the database, it is logged in the LOGTAB table. The
SMODE value specifies the activity as an entry or an exit. Calling this function as a
Post Process Function as well returns results such as those shown in the table
below.
Setting Up a JDBC Connection to the Data Source
Make sure all prerequisites have been met before setting up a JDBC connection to a
data source:
•
The JDBC driver for the selected database must be available to BI Publisher. If
you are using an Oracle database or one of the DataDirect drivers provided by
WebLogic Server, then the drivers must be installed in the correct location and
there is no further setup required.
9-5
Chapter 9
Setting Up a JDBC Connection to the Data Source
•
If you plan to use a different version of any of the drivers installed with WebLogic
Server, then you can replace the driver file in WL_HOME\server\lib with an
updated version of the file or add the new file to the front of your CLASSPATH.
If you plan to use a third-party JDBC driver that is not installed with WebLogic
Server, then you must update the WebLogic Server classpath to include the
location of the JDBC driver classes as described in Command Reference for
Oracle WebLogic Server.
See Administering JDBC Data Sources for Oracle WebLogic Server.
Note:
When the JDBC connection is defined, the administrator defines the user that
BI Publisher uses to connect to the database. It is the responsibility of the
administrator to establish security on the database to allow or disallow actions
this user can take on the database schema.
For report consumer access to data that is returned in a report, the
administrator and data model developer can establish security, if needed, that
can limit the data viewed by a particular BI Publisher user. One method for
securing data returned is to use pre-process and post-process function calls to
pass the xdo_username. See About Pre Process Functions and Post Process
Functions.
To set up a JDBC connection to a data source:
1.
From the Administration page, click JDBC Connection to display the list of
existing JDBC connections.
Private JDBC connections are also supported. See Data Modeling Guide for
Oracle Business Intelligence Publisher.
2.
Click Add Data Source.
3.
Enter the following fields for the new connection:
•
Data Source Name — Enter a display name for the data source. This name is
displayed in the Data Source selection list in the Data Model Editor.
•
Driver Type — Select the database type from the list. When you select a
driver type, BI Publisher automatically displays the appropriate Database
Driver Class and provides the appropriate Connection String format for your
selected database.
•
Database Driver Class — This is automatically entered based on your
selection for Driver Type. You can update this field if desired.
For example: oracle.jdbc.OracleDriver or
hyperion.jdbc.sqlserver.SQLServerDriver
•
Connection String — Enter the database connection string.
Example connection strings:
–
Oracle database
For an Oracle database (non-RAC) the connect string must have the
following format:
9-6
Chapter 9
Setting Up a JDBC Connection to the Data Source
jdbc:oracle:thin:@[host]:[port]:[sid]
For example: jdbc:oracle:thin:@myhost.us.example.com:1521:prod
–
Oracle RAC database
To connect to an Oracle RAC database, use the following format:
jdbc:oracle:thin:@//<host>[:<port>]/<service_name>
For example: jdbc:oracle:thin:@//myhost.example.com:1521/my_service
–
Microsoft SQL Server
For a Microsoft SQL Server, the connect string must have the following
format:
jdbc:hyperion:sqlserver://[hostname]:
[port];DatabaseName=[Databasename]
For example:
jdbc:hyperion:sqlserver://myhost.us.example.com:
7777;DatabaseName=mydatabase
•
Use System User — This is reserved for connections to the Oracle BI Server.
See Setting Up a JDBC Connection to the Oracle BI Server.
4.
•
User Name — Enter the user name required to access the data source on the
database.
•
Password — Enter the password associated with the user name for access to
the data source on the database.
•
Pre Process Function and Post Process Function — (Optional) Enter a
PL/SQL function to execute when a connection is created (Pre Process) or
closed (Post Process). See About Pre Process Functions and Post Process
Functions.
•
Use Proxy Authentication — Select this box to enable Proxy Authentication.
See About Proxy Authentication .
Click Test Connection. A confirmation is displayed.
The figure below shows the general settings of the JDBC connection page.
9-7
Chapter 9
Setting Up a JDBC Connection to the Data Source
5.
(Optional) Enable a backup database for this connection by entering the following:
•
Use Backup Data Source — Select this box.
•
Connection String — Enter the connection string for the backup database.
•
Username / Password — Enter the username and password for this
database.
•
Click Test Connection. A confirmation is displayed.
The figure below shows the Backup Data Source region of the page.
6.
Define security for this data source. Use the shuttle buttons to move roles from the
Available Roles list to the Allowed Roles list. Only users assigned the roles on the
Allowed Roles list can create or view reports from this data source.
The settings defined here are passed down to the backup data source, if one is
defined.
9-8
Chapter 9
Setting Up a Database Connection Using a JNDI Connection Pool
Setting Up a Database Connection Using a JNDI
Connection Pool
BI Publisher supports connecting to the JDBC data source through a connection pool.
Using a connection pool increases efficiency by maintaining a cache of physical
connections that can be reused. When a client closes a connection, the connection
gets placed back into the pool so that another client can use it. A connection pool
improves performance and scalability by allowing multiple clients to share a small
number of physical connections. You set up the connection pool in your application
server and access it through Java Naming and Directory Interface (JNDI).
After you set up the connection pool in your application server, enter the required
fields in this page so that BI Publisher can use the pool to establish connections. See
Configuring JDBC Data Sources in Administering JDBC Data Sources for Oracle
WebLogic Server.
To set up a database connection using a JNDI connection pool:
1.
From the Administration page, click JNDI Connection to display the list of existing
JNDI connections.
2.
Click Add Data Source.
3.
Enter the following fields for the new connection:
•
Data Source Name — Enter a display name for the data source. This name is
displayed in the Data Source selection list in the Data Model Editor.
•
JNDI Name — Enter the JNDI location for the pool. For example, jdbc/
BIPSource.
•
Use Proxy Authentication — Select this box to enable Proxy Authentication.
See About Proxy Authentication.
4.
Click Test Connection. A confirmation message is displayed.
5.
Define security for this data source. Use the shuttle buttons to move roles from the
Available Roles list to the Allowed Roles list. Only users assigned the roles on the
Allowed Roles list can create or view reports from this the data source.
Setting Up a Connection to an LDAP Server Data Source
You set up a connection to an LDAP data source from the Administration page.
To set up a connection to an LDAP data source:
1.
From the Administration page, select LDAP Connection to display the list of
existing LDAP connections.
2.
Click Add Data Source.
3.
Enter the following fields for the new connection:
•
Enter the Data Source Name — This is the display name that is displayed in
the Data Source selection list in the Data Model Editor.
•
Enter the LDAP Connection URL for the LDAP server in the format:ldap://
hostname:port.
9-9
Chapter 9
Setting Up a Connection to an OLAP Data Source
•
Enter the Username (for example:
cn=admin,cn=users,dc=us,dc=company,dc=com).
•
Password — Enter the password if required.
•
Enter the JNDI Context Factor Class (for example:
com.sun.jndi.ldap.LdapCtxFactory).
4.
Click Test Connection.
5.
Define security for this data source. Use the shuttle buttons to move roles from the
Available Roles list to the Allowed Roles list. Only users assigned the roles on the
Allowed Roles list can create data models from this the data source or view
reports that run against this data source.
Setting Up a Connection to an OLAP Data Source
BI Publisher supports connecting to several types of OLAP databases.
Note that to connect to Microsoft SQL Server Analysis Services, BI Publisher must be
installed on a supported Windows operating system. For the complete list of supported
OLAP databases, see System Requirements and Certification.
To set up a connection to an OLAP data source:
1.
From the Administration page, click OLAP Connection to display the list of
existing OLAP connections.
Private OLAP connections are also supported. For more information, see
Managing Private Data Sources in Data Modeling Guide for Oracle Business
Intelligence Publisher.
2.
Click Add Data Source.
3.
Enter the following fields for the new connection:
•
Data Source Name — Enter a display name for the data source. This name is
displayed in the Data Source selection list in the Data Model Editor.
•
OLAP Type — Select from the list of supported OLAP databases. When you
select the type, the OLAP Connection String field is updated with the
appropriate connection string format for your selection.
•
OLAP Connection String — Enter the connection string for the OLAP
database. Following are examples for each of the supported OLAP types:
–
Oracle's Hyperion Essbase
Format: [server]
Example: myServer.us.example.com
–
Microsoft SQL Server 2000 Analysis Services
Format: Data Source=[server];Provider=msolap;Initial Catalog=[catalog]
Example: Data Source=myServer;Provider=msolap;Initial
Catalog=VideoStore
–
Microsoft SQL Server 2005 Analysis Services
Format: Data Source=[server];Provider=msolap.3;Initial Catalog=[catalog]
Example: Data Source=myServer;Provider=msolap.3;Initial
Catalog=VideoStore
9-10
Chapter 9
Setting Up a Connection to a File Data Source
–
SAP BW
Format: ASHOST=[server] SYSNR=[system number] CLIENT=[client]
LANG=[language]
Example: ASHOST=172.16.57.44 SYSNR=01 CLIENT=800 LANG=EN
•
Username and Password for the OLAP database
4.
Click Test Connection. A confirmation message is displayed.
5.
Define security for this data source. Use the shuttle buttons to move roles from the
Available Roles list to the Allowed Roles list. Only users assigned the roles on the
Allowed Roles list can create or view reports from this the data source.
Setting Up a Connection to a File Data Source
BI Publisher enables you to use existing XML or Microsoft Excel files created from
other sources as input to your BI Publisher reports.
To use a file as a data source, it must reside in a directory that BI Publisher can
connect to. Set up the connection details to the file data source directory using this
page.
To set up a connection to a file data source:
1.
From the Administration page, click File to display the list of existing file sources.
2.
Click Add Data Source.
3.
Enter the following fields for the new data source:
4.
•
Data Source Name — Enter a display name for the data source. This name is
displayed in the Data Source selection list in the Data Model Editor.
•
Path — Enter the full path to the top-level directory on your server. Users can
access files in this directory and any subdirectories.
Define security for this data source. Use the shuttle buttons to move roles from the
Available Roles list to the Allowed Roles list. Only users assigned the roles on the
Allowed Roles list can create or view reports from this data source.
Setting Up a Connection to a Web Service
BI Publisher supports Web service data sources that return valid XML data.
Note:
Additional configuration may be required to access external Web services
depending on your system's security. If the WSDL URL is outside the
company firewall, see Configuring Proxy Settings.
BI Publisher supports Web services that return both simple and complex data types.
You must make the distinction between simple and complex when you define the Web
service connection. For more information about each Web service connection type,
see Adding a Simple Web Service and Adding a Complex Web Service.
9-11
Chapter 9
Setting Up a Connection to a Web Service
If the Web service is protected by Secure Sockets Layer (SSL), see Configuring BI
Publisher for Secure Socket Layer (SSL) Communication.
Private Web Service connections are also supported. For more information, see
Managing Private Data Sources in Data Modeling Guide for Oracle Business
Intelligence Publisher.
Only Basic and Digest authentication is supported for Web service data sources.
Only document/literal Web services are supported.
Adding a Simple Web Service
You add a simple Web service from the Administration page.
To add a Web service as a data source:
1.
From the Administration page, click Web Service Connection to display the list of
existing Web service connections.
2.
On the Web Services tab, click Add Data Source to display the Add Data Source
page as shown in the figure below.
3.
Enter the following fields for the new connection:
•
Data Source Name — Enter a display name for the data source. This name is
displayed in the Data Source selection list in the Data Model Editor.
•
Server Protocol — Select the server protocol.
•
Server — Enter the server name.
•
Port — Enter the server port.
•
URL Suffix — Enter the URL suffix for the web service connection.
For example, stockquote.asmx?WSDL
9-12
Chapter 9
Setting Up a Connection to a Web Service
•
(Optional) Session Timeout (Minutes) — Enter the timeout in minutes. If the
BI Publisher server cannot establish a connection to the Web service, the
connection attempt will time out after the specified time out period has
elapsed.
•
Complex Type — Deselect the check box to designate the connection as a
simple Web service.
4.
Define security for this data source by using the shuttle buttons to move roles from
the Available Roles list to the Allowed Roles list. Only users assigned the roles
on the Allowed Roles list can create or view reports from this data source.
5.
Click Apply to save the data source connection.
Adding a Complex Web Service
You add a complex Web service from the Administration page.
To add a complex Web service as a data source:
1.
From the Administration page, click Web Service Connection to display the list of
existing Web service connections.
2.
Click Add Data Source to display the Add Data Source page as shown in the
figure below.
3.
Enter the following fields for the new connection:
•
Data Source Name — Enter a display name for the data source. This name is
displayed in the Data Source selection list in the Data Model Editor.
•
Server Protocol — Select the server protocol.
•
Server — Enter the server name.
9-13
Chapter 9
Setting Up a Connection to a HTTP XML Feed
•
Port — Enter the server port.
•
URL Suffix — Enter the URL for the Web service connection.
•
(Optional) Session Timeout (Minutes) — Enter the timeout in minutes. If the
BI Publisher server cannot establish a connection to the web service, the
connection attempt times out after the specified time out period has elapsed.
•
Complex Type — Select the check box to designate the connection as a
complex Web service.
•
WS-Security — Select the security header.
–
2002 — Enables the "WS-Security" Username Token with the 2002
namespace:
http://docs.oasis-open.org/wss/2004/01/oasis-200401wss-wssecurity-secext-1.0.xsd
–
2004 — Enables the "WS-Security" Username Token with the 2004
namespace:
http://docs.oasis-open.org/wss/2004/01/oasis-200401wss-username-token-profile-1.0#PasswordText
4.
•
Authentication Type — BI Publisher supports HTTP and SOAP
authentication types. SOAP is the default. When HTTP is selected, the user
name and password information are passed through HTTP headers. When
soap is selected, the user name and password information are passed through
XML SOAP envelope headers.
•
Username — Enter the user name for the web service, if required.
•
Password — Enter the password for the web service, if required.
•
WSDL protected by HTTP basic auth — select if access to the WSDL is
protected. When the WSDL is protected by user name and password, BI
Publisher executes an HTTP call with the username and password to access
the WSDL URL. The WSDL can then be downloaded and parsed by BI
Publisher.
Define security for this data source. Use the shuttle buttons to move roles from the
Available Roles list to the Allowed Roles list. Only users assigned the roles on
the Allowed Roles list can create or view reports from this data source.
The settings defined here are passed down to the backup data source, if one is
defined.
5.
Click Apply.
Setting Up a Connection to a HTTP XML Feed
HTTP (XML Feed) data sources enable your data model designers to build data
models from RSS and XML feeds over the Web by retrieving data through the HTTP
GET method.
Private HTTP XML connections are also supported. For more information, see
Managing Private Data Sources in Data Modeling Guide for Oracle Business
Intelligence Publisher.
To add a HTTP XML as a data source:
9-14
Chapter 9
Setting Up a Connection to a HTTP XML Feed
1.
From the Administration page, click HTTP Connection to display the list of
existing HTTP connections.
2.
Click Add Data Source to display the Add Data Source page as shown below.
3.
Enter the following fields for the new connection:
•
Data Source Name — Enter a display name for the data source. This name is
displayed in the Data Source selection list in the Data Model Editor.
•
Server Protocol — Select the server protocol.
•
Server — Enter the server name.
•
Port — Enter the server port.
•
Realm — Enter the URL for the web service connection.
For example:
xmlpserver/services/v2/SecurityService?wsdl
4.
•
Username — Enter the user name required to access the data source on the
database.
•
Password — Enter the password associated with the user name for access to
the data source on the database.
Define security for this data source. Use the shuttle buttons to move roles from the
Available Roles list to the Allowed Roles list. Only users assigned the roles on the
Allowed Roles list can create or view reports from this data source.
The settings defined here are passed down to the backup data source, if one is
defined.
9-15
Chapter 9
Setting Up a Connection to a Content Server
Setting Up a Connection to a Content Server
Content Server data source enables you to retrieve a text attachment content stored in
Universal Content Management (UCM) server and display it in the report of the
corresponding document.
To set up a connection to a Content Server data source:
1.
From the Administration page, select the Content Server link.
2.
Click Add Data Source in the Data Sources page.
3.
Enter the name in the Data Source Name field.
4.
Enter the URL in the URI field.
5.
Enter the username and password in the Username and Password fields,
respectively.
6.
Click Test Connection.
Note:
You will see a confirmation message that your connection is established
successfully.
7.
Click Apply to save the data source details after your connection is successful.
Viewing or Updating a Data Source
You can view or update a data source from the Administration page.
To view or update a data source:
9-16
Chapter 9
Viewing or Updating a Data Source
1.
From the Administration page, select the Data Source type to update.
2.
Select the name of the connection to view or update. All fields are editable. See
the appropriate section for setting up the data source type for information on the
required fields.
3.
Select Apply to apply any changes or Cancel to exit the update page.
9-17
10
Setting Up Delivery Destinations
This chapter describes the setup required to deliver BI Publisher reports to printers, email servers, FTP servers, WebDav servers, content servers, and cloud server. It also
describes how to set up the HTTP notification server.
It covers the following topics:
•
Configuring Delivery Options
•
Adding a Printer
•
Adding a Fax Server
•
Adding an E-Mail Server
•
Adding a WebDAV Server
•
Adding an HTTP Server
•
Adding an FTP Server
•
Adding a Content Server
•
Adding a Common UNIX Printing System (CUPS) Server
•
Adding a Cloud Server
Configuring Delivery Options
Use the Delivery Configuration Options page to set general properties for e-mail
deliveries and notifications from BI Publisher and for defining the SSL certificate file.
To configure delivery options:
1.
From the Administration page, select Delivery Configuration, as shown below.
10-1
Chapter 10
Adding a Printer
2.
Enter the following properties:
•
SSL Certificate File — If SSL is enabled for your installation, then you can
leave this field empty if you want to use the default certificates built-in with BI
Publisher. SSL works with the default certificate if the server uses the
certificate signed by a trusted certificate authority such as Verisign. This field
is mandatory only if the user uses the SSL with a self-signed certificate. The
self-signed certificate means the certificate is signed by a non-trusted
certificate authority (usually the user).
•
E-mail From Address — Enter the From address to appear on e-mail report
deliveries from the BI Publisher server. The default value is [email protected]
•
Delivery Notification E-mail From Address — Enter the From address to
appear on notifications delivered from the BI Publisher server. The default
value is [email protected]
•
Success Notification Subject — Enter the subject line to display for e-mail
notification recipients when the report status is Success.
•
Warning Notification Subject — Enter the subject line to display for e-mail
notification recipients when the report status is Warning.
•
Failure Notification Subject — Enter the subject line to display for e-mail
notification recipients when the report status is Failed.
•
Skipped Notification Subject — Enter the subject line to display for e-mail
notification recipients when the report status is Skipped.
•
Use System Proxy Settings - When selected, the Delivery Manager looks up
the proxy server settings from the Java runtime environment.
Note the following:
–
Printer, Fax, WebDAV, HTTP and CUPS servers use proxy settings for
http protocol when SSL is not used. When SSL is used, the and https
proxy setting is used.
–
FTP and SFTP use proxy settings for FTP.
–
Contents servers and email servers do not support connection over a
proxy, regardless of this setting.
You can override the proxy settings per delivery server, using proxy
configuration fields on the individual server setup page. If a proxy server and
ports are configured for a delivery server, the Delivery Manager uses the proxy
server and port configured for the server instead of the one defined in the Java
Runtime environment. In Cloud installations, this check box is always selected,
and cannot be turned off or overridden by individual server settings.
Adding a Printer
Regardless of whether BI Publisher is running on Linux, Unix, or Windows, the printer
destination can be any IPP server.
The IPP server can be the printer itself, which is the easiest option, but if the printer
does not natively support IPP, you can set up a print server that does support IPP
(such as CUPS) and connect BI Publisher to the print server and then the print server
to the printer. In this print server scenario, the print server can run on any operating
system.
10-2
Chapter 10
Adding a Printer
To send fax from BI Publisher, you must set up Common Unix Printing Service
(CUPS) and the fax4CUPS extension, to enable connection to your fax server from BI
Publisher. The fax set up requires this plugin to the CUPS server on the operating
system. Note that the Administration page makes the distinction between a fax and a
printer server in the UI, so that users can pick one or the other or both at runtime.
Even though the fax and printer server that the users see can both use a single CUPS
server.
For information on setting up CUPS or Windows IPP print servers and how to connect
network printers to them, refer to the CUPS or Windows IPP software vendor
documentation.
Two types of security are supported: Basic and Digest.
About Printing PDF
PDF is a popular output format for business reports and is printable from viewer
software such as Adobe Reader. However, some reports require printing directly from
the report server. For example, paychecks and invoices are usually printed as
scheduled batch jobs. Some newer printers with PostScript Level 3 compliant Raster
Image Processing can natively support PDF documents, but there are still many
printers in business use that only support PostScript Level 2 that cannot print PDF
documents directly.
To print PDF documents directly from the BI Publisher server if your printer or print
server does not support printing PDF, you have the following options:
•
Select one of BI Publisher's filters: PDF to PostScript or PDF to PCL.
•
Configure a custom, or third-party filter.
After completing all other required fields for the print server, you can schedule reports
to print directly from the BI Publisher server to any printer in your system that supports
PostScript Level 2.
Setting Up a Printer
You set up printers from the Administration page.
To set up a printer:
1.
From the Admin page select Printer. Select Add Server.
2.
Enter the following required fields:
•
Server Name — Enter a unique name. Example: Localprinter
•
URI — Enter the Uniform Resource Identifier for the printer.
Example: ipp://myhost:631/printers/myprinter
Example URI syntax for Windows IPP server: http://ip-address/
printers/name-printer/.printer
3.
Enter a Filter (optional).
A filter enables you to call a conversion utility to convert the PDF generated by BI
Publisher to a file format supported by your specific printer type. BI Publisher
provides the following filters:
•
PDF to PostScript
10-3
Chapter 10
Adding a Printer
BI Publisher includes a PDF to PostScript filter. This filter converts PDF to
PostScript Level 2. Select PDF to PostScript from the list to use BI
Publisher's predefined filter.
•
PDF to PCL
To convert PDF to PCL, select PDF to PCL. This automatically populates the
Filter Command field.
BI Publisher supports the PDF to PCL conversion only for font selection
requirements for check printing. For generic printing requirements, use the
PDF to PostScript filter.
You can embed PCL commands into RTF templates to invoke the PCL
commands at a specific position on the PCL page; for example, to use a font
installed on the printer for routing and account numbers on a check. For more
information, see Embedding PCL Commands for Check Printing in Report
Designer's Guide for Oracle Business Intelligence Publisher.
You can also call a custom filter using operating system commands.
About Custom Filters
To specify a custom filter, pass the native OS command string with the two
placeholders for the input and output filename, {infile} and {outfile}.
This is useful especially if you are trying to call IPP printers directly or IPP printers
on Microsoft Internet Information Service (IIS). Unlike CUPS, those print servers
do not translate the print file to a format the printer can understand, therefore only
limited document formats are supported. With the filter functionality, you can call
any of the native OS commands to transform the document to the format that the
target printer can understand.
For example, to transform a PDF document to a PostScript format, enter the
following PDF to PS command in the Filterfield:
pdftops {infile} {outfile}
To call an HP LaserJet printer setup on a Microsoft IIS from Linux, you can set
Ghostscript as a filter to transform the PDF document into the format that the HP
LaserJet can understand. To do this, enter the following Ghostscript command in
the Filter field:
gs -q -dNOPAUSE -dBATCH -sDEVICE=laserjet -sOutputFile={outfile} {infile}
For fax servers, you can use the filter to transform the file to Tag Image File
Format (TIFF).
4.
Optionally enter the following fields if appropriate:
•
Security fields — Username and Password, Authentication Type (None,
Basic, Digest) and Encryption Type (None, SSL).
•
Proxy Server fields — Host, Port, User Name, Password, Authentication
Type (None, Basic, Digest)
10-4
Chapter 10
Adding a Fax Server
Adding a Fax Server
To send fax from BI Publisher, you must set up Common Unix Printing Service
(CUPS) and the fax4CUPS extension, to enable fax transmissions from BI Publisher.
See the following resources for information about setting up CUPS and the fax4CUPS
extension:
To set up fax delivery:
1.
From the Administration page, select Fax. Select Add Server.
2.
Enter the following required fields:
3.
•
Server Name — Enter a unique name. Example: Localprinter
•
URI — Enter the Uniform Resource Identifier for the printer. Example: ipp://
myhost:631/printers/myprinter
Enter a Filter (optional).
A filter enables you to call a conversion utility to convert the PDF generated by BI
Publisher to a file format supported by your specific printer type. BI Publisher
provides the following filters:
•
PDF to PostScript
BI Publisher includes a PDF to PostScript filter. This filter converts PDF to
PostScript Level 2. Select PDF to PostScript from the list to use BI
Publisher's predefined filter.
•
PDF to PCL
To convert PDF to PCL, select PDF to PCL. This automatically populates the
Filter Command field.
BI Publisher supports the PDF to PCL conversion only for font selection
requirements for check printing. For generic printing requirements, use the
PDF to PostScript filter.
You can embed PCL commands into RTF templates to invoke the PCL
commands at a specific position on the PCL page; for example, to use a font
installed on the printer for routing and account numbers on a check. For more
information, see Embedding PCL Commands for Check Printing in Report
Designer's Guide for Oracle Business Intelligence Publisher.
You can also call a custom filter using operating system commands.
About Custom Filters
To specify a custom filter, pass the native OS command string with the two
placeholders for the input and output filename, {infile} and {outfile}.
This is useful especially if you are trying to call IPP printers directly or IPP printers
on Microsoft Internet Information Service (IIS). Unlike CUPS, those print servers
do not translate the print file to a format the printer can understand, therefore only
limited document formats are supported. With the filter functionality, you can call
any of the native OS commands to transform the document to the format that the
target printer can understand.
For example, to transform a PDF document to a PostScript format, enter the
following PDF to PS command in the Filter field:
10-5
Chapter 10
Adding an E-Mail Server
pdftops {infile} {outfile}
To call an HP LaserJet printer setup on a Microsoft IIS from Linux, you can set
Ghostscript as a filter to transform the PDF document into the format that the HP
LaserJet can understand. To do this, enter the following Ghostscript command in
the Filter field:
gs -q -dNOPAUSE -dBATCH -sDEVICE=laserjet -sOutputFile={outfile} {infile}
For fax servers, you can use the filter to transform the file to Tag Image File
Format (TIFF).
4.
Optionally enter the following fields if appropriate:
•
Security fields — Username and Password, Authentication Type (None,
Basic, Digest) and Encryption Type (None, SSL).
•
Proxy Server fields — Host, Port, User Name, Password, Authentication
Type (None, Basic, Digest)
Adding an E-Mail Server
You add an e-mail server from the Administration page.
To add an e-mail server:
1.
From the Administration page, select Email. This displays the list of servers that
have been added. Select Add Server.
2.
Enter the Server Name, Host, and Port for the e-mail server.
3.
Select a Secure Connection method to use for connections with the e-mail
server. The options are:
4.
•
None
•
SSL — Use Secure Socket Layer.
•
TLS (Transport Layer Security) — Use TLS when the server supports the
protocol; SSL is accepted in the response.
•
TLS Required — If the server does not support TLS, then the connection is not
made.
Optionally enter the following fields if appropriate:
•
General fields — Port
•
Security fields — Username and Password.
Adding a WebDAV Server
You add a WebDAV server from the Administration page.
To add a WebDAV server:
1.
From the Administration page, select WebDAV to display the list of servers that
have been added. Select Add Server.
2.
Enter the Name and Host for the new server.
3.
Optionally enter the following fields if appropriate:
•
General fields — Port
10-6
Chapter 10
Adding an HTTP Server
•
Security fields — Authentication Type (None, Basic, Digest) and Encryption
Type (None, SSL).
•
Proxy Server fields — Host, Port, User Name, Password, Authentication
Type (None, Basic, Digest)
Adding an HTTP Server
You can register an application URL or postprocess HTTP URL as an HTTP server to
send a notification request to after the report has completed.
The HTTP notification sent by BI Publisher posts a form data for Job ID, report URL
and Job Status to the HTTP Server URL page.
To set up an HTTP notification to integrate with a third-party application, see
Developer's Guide for Oracle Business Intelligence Publisher. To enable an HTTP
notification for a scheduled report, see Configuring Notifications in User's Guide for
Oracle Business Intelligence Publisher.
To add an HTTP server
1.
From the Administration page, select HTTP to display the list of servers that have
been added. Select Add Server.
2.
Enter a name for the server, and enter the URL. When the report finishes
processing, BI Publisher posts form data for Job ID, report URL and Job Status.
3.
Enter the Security information, if required. If your server is password protected,
enter the Username and Password. Select the Authentication Type: None,
Basic, or Digest; and Encryption Type: None or SSL.
4.
If the notification is to be sent through a proxy server, enter the fully qualified Host
name, the Port, the Username and Password, and Authentication Type of the
proxy server.
Adding an FTP Server
You can add an FTP server from the Administration page.
Note:
If the destination file name supplied to the BI Publisher scheduler contains
non-ascii characters, BI Publisher will use UTF-8 encoding to specify the file
name to the destination FTP server. Your FTP server must support UTF-8
encoding or the job delivery will fail with "Delivery Failed" error message.
To add an FTP server:
1.
From the Administration page, under Delivery, click FTP to display the list of
servers that have been added.
2.
Click Add Server.
3.
Enter the following fields for the FTP server:
•
Server Name — For example, myFTPserver.
10-7
Chapter 10
Adding an FTP Server
•
Host — For example, myhost.company.com.
•
Port — The default for FTP is 21.
The default for Secure FTP (SFTP) is 22.
If you wish to use the defaults at run time, you can leave this field empty, BI
Publisher automatically uses 21 for FTP and 22 for SFTP.
However, if you wish to use the Test Connection option from the UI, you must
supply the correct port number in this field. Specify 21 for FTP or 22 for SFTP.
•
Use Secure FTP — Select this box to enable Secure FTP (SFTP). Ensure you
set the Port to 22 for SFTP. See SSH Options for SFTP.
•
Use Passive Mode — Passive mode is recommended when the FTP server is
behind a firewall.
•
Host Key Fingerprint — Host key verification is a key security feature. If
<hostKeyFingerprint> value is set, the value must match the fingerprint
calculated from server's host key at runtime. If it does not match, an exception
error is thrown. When you connect the first time, the Delivery Manager API
allows you to retrieve the server key fingerprint.
•
Filter Command (optional) — You can use a custom filter to apply file
conversion such as encryption. To specify a custom filter, pass the native
Operating System command string with the two placeholders for the input and
output filename, {infile} and {outfile}.
For example, to set up PGP encryption of the file using a Filter Command,
enter the following:
gpg -e -r myKey -o {outfile} {infile}
where
myKey is the ID to gpg key (such as real name, email address, or fingerprint).
The Filter command field does not support quotes. Therefore you cannot use
certain valid gpg formats that include spaces, for example: "myname
<[email protected]>"). You must specify the ID in a single string with no
spaces.
•
Create files with Part extension when copy is in process — Select this box
if you want BI Publisher to create the file on the FTP server with a .part
extension while the file is transferring. The .part extension indicates that the
file transfer is not complete. When the file transfer is complete, the file is
renamed without the .part extension. If the file transfer does not complete, the
file with the .part extension remains on the server.
4.
Enter a username and Password for the server if required.
5.
Enter Proxy Server information — Host, Port, Username, Password,
Authentication type
The following figure shows a sample SFTP delivery server setup:
10-8
Chapter 10
Adding an FTP Server
SSH Options for SFTP
Secure File Transfer Protocol (SFTP) is based on the Secure Shell technology (SSH).
Oracle BI Publisher supports the following SSH options for SFTP delivery.
SSH Option
Supported Values
Cipher Suites
•
•
•
•
•
•
3des-cbc
blowfish-cbc
aes128-cbc
aes128-ctr
aes192-ctr
aes256-ctr
Note:
You can use aes192-ctr and aes256-ctr cipher
suites only when BI Publisher is running on a
JVM on which the Java Cryptography
Extension (JCE) unlimited strength jurisdiction
policy files are installed.
Key Exchange Method
•
•
•
•
diffie-hellman-group1-sha1
diffie-hellman-group14-sha1
diffie-hellman-group-exchange-sha1
diffie-hellman-group-exchange-sha256
Note:
You can use diffie-hellman-group-exchangesha256 key exchange methods only when BI
Publisher is running on a JVM on which the
Java Cryptography Extension (JCE) unlimited
strength jurisdiction policy files are installed.
Public Key Algorithm
•
•
ssh-dss
ssh-rsa
10-9
Chapter 10
Adding a Content Server
Adding a Content Server
You can deliver documents generated by BI Publisher to your Oracle WebContent
Server.
BI Publisher's integration with the content server provides the following features:
•
At run time, the report consumer can tag the report with Security Group and
Account metadata (if applicable) to ensure that the appropriate access rights are
applied to the document when delivered.
See Adding Destinations in User's Guide for Oracle Business Intelligence
Publisher.
•
For documents that require specific custom metadata fields (such as invoice
number, customer name, order date), BI Publisher enables the report author to
map the custom metadata fields defined in Content Profile Rule Sets to data fields
in the data model.
See Adding Custom Metadata for Oracle WebCenter Content Server in Data
Modeling Guide for Oracle Business Intelligence Publisher.
BI Publisher communicates with Oracle WebCenter Content Server using the Remote
Intradoc Client (RIDC). The connection protocols therefore follow the standards
required by the RIDC. The protocols supported are:
•
Intradoc: The Intradoc protocol communicates to the Content Server over the over
the Intradoc socket port (typically 4444). This protocol requires a trusted
connection between the client and Content Server and will not perform any
password validation. Clients that use this protocol are expected to perform any
required authentication themselves before making RIDC calls. The Intradoc
communication can also be configured to run over SSL.
•
HTTP and HTTPS: The HTTP protocol connection requires valid user name and
password authentication credentials for each request. You supply the credentials
to use for requests in the BI Publisher Administration page.
•
JAX-WS: The JAX-WS protocol is supported only in Oracle WebCenter Content
11g with a properly configured Content Server instance and the RIDC client
installed. JAX-WS is not supported outside this environment.
For more information about these protocols, see Using RIDC to Access Content
Server in Developing with Oracle WebCenter Content.
10-10
Chapter 10
Adding a Content Server
To set up a connection to a content server as a delivery destination:
1.
From the Administration page, under Delivery, click Content Server to display the
list of servers that have been added. Click Add Server.
2.
Enter the Server Name, for example: contentserver01.
3.
Enter the connection URI for your content server. The URI can take any of the
following supported protocols:
•
HTTP/HTTPS — Specifies the URL to the Content Server CGI path.
For example:
•
•
–
http://localhost:16200/cs/idcplg
–
https://localhost:16200/cs/idcplg
Intradoc — The Intradoc protocol communicates to the Content Server over
the Intradoc socket port (typically 4444). The IDC protocol also supports
communication over SSL. For example:
–
idc://host:4444
–
idcs://host:4443
JAX-WS — Uses the JAX-WS protocol to connect to the Content Server.
For example:
–
4.
http://wlsserver:16200/idcnativews
To enable the inclusion of custom metadata with your report documents delivered
to the content server, select the Enable Custom Metadata check box. This option
must be selected to enable the custom metadata options in the Data Model Editor
and the Scheduler.
10-11
Chapter 10
Adding a Common UNIX Printing System (CUPS) Server
Adding a Common UNIX Printing System (CUPS) Server
You add CUPS servers from the Administration page.
See Adding a Printer for information about when you must configure CUPS.
To add a CUPS server:
1.
From the Administration page, select CUPS to display the list of servers that have
been added.
2.
Select Add Server.
3.
Enter the Server Name and Host and Port for the CUPS server.
Adding a Cloud Server
BI Publisher can deliver reports to Oracle Document Cloud Services through a cloud
server for enabling easy access and report sharing on the cloud.
To add a cloud server
1.
Login to BI Publisher with administrator privileges, navigate to Administration >
Document Cloud Services.
2.
Click Add Server.
3.
In the Server Name field, type the name of the cloud server through which the BI
Publisher must deliver the reports to Oracle Document Cloud Services.
4.
In the URI field, type the URI of the cloud server. For example, https://
host.oraclecloud.com.
5.
In the Username and Password fields, provide the credentials for accessing the
cloud server.
6.
Click Test Connection to ensure that the cloud server connection works.
7.
Click Apply to save.
10-12
11
Defining Runtime Configurations
This chapter describes processing properties for BI Publisher including PDF document
security, FO processing, font mapping, and specific properties for each output type.
It covers the following topics:
•
Setting Runtime Properties
•
PDF Output Properties
•
PDF Digital Signature Properties
•
PDF/A Output Properties
•
PDF/X Output Properties
•
DOCX Output Properties
•
RTF Output Properties
•
HTML Output Properties
•
FO Processing Properties
•
RTF Template Properties
•
PDF Template Properties
•
Flash Template Properties
•
CSV Output Properties
•
Excel 2007 Output Properties
•
All Outputs Properties
•
Memory Guard & Data Model Properties
•
Defining Font Mappings
•
Defining Currency Formats
Setting Runtime Properties
The Runtime Configuration page enables you to set runtime properties at the server
level.
These same properties can also be set at the report level, from the report editor's
Properties dialog. See Configuring Report Properties in Report Designer's Guide for
Oracle Business Intelligence Publisher. If different values are set for a property at each
level, then report level takes precedence.
PDF Output Properties
Generate the type of PDF files you want by setting available output properties.
11-1
Chapter 11
PDF Output Properties
Property Name
Description
Compress PDF output Specify "true" or "false" to control
compression of the output PDF
file.
Hide PDF viewer's
menu bars
Default
Internal Name
true
pdf-compression
Specify "true" to hide the viewer
false
application's menu bar when the
document is active. The menu bar
option is only effective when
using the Export button, which
displays the output in a
standalone Acrobat Reader
application outside of the
browser.
Hide PDF viewer's tool Specify "true" to hide the viewer
bars
application's toolbar when the
document is active.
false
pdf-hide-menubar
pdf-hide-toolbar
Replace smart quotes
Set to "false" if you do not want
true
curly quotes replaced with straight
quotes in the PDF output.
pdf-replacesmartquotes
Enable PDF Security
If you specify "true," then the
output PDF file is encrypted. You
can then also specify the
following properties:
pdf-security
•
•
•
false
Open document password
Modify permissions password
Encryption Level
Open document
password
This password is required for
N/A
opening the document. It enables
users to open the document only.
This property is enabled only
when "Enable PDF Security" is
set to "true". Note that BI
Publisher follows Adobe's
password restrictions. The
password must contain only Latin
1 characters and must be no
more than 32 bytes long.
pdf-open-password
Modify permissions
password
This password enables users to
override the security setting. This
property is effective only when
"Enable PDF Security" is set to
"true". Note that BI Publisher
follows the Adobe's password
restrictions. The password must
contain only Latin 1 characters
and must be no more than 32
bytes long.
pdf-permissionspassword
N/A
11-2
Chapter 11
PDF Output Properties
Property Name
Description
Default
Internal Name
Encryption level
Specify the encryption level for
the output PDF file. The possible
values are:
2 - high
pdf-encryptionlevel
•
0: Low (40-bit RC4, Acrobat
3.0 or later)
•
1: Medium (128-bit RC4,
Acrobat 5.0 or later)
•
2: High (128-bit AES, Acrobat
7.0 or later)
This property is effective only
when "Enable PDF Security" is
set to "true". When Encryption
level is set to 0, you can also set
the following properties:
•
•
Disable printing
Disable document
modification
•
Disable context copying,
extraction, and accessibility
•
Disable adding or changing
comments and form fields
When Encryption level is set to 1
or higher, the following properties
are available:
•
•
•
•
Enable text access for screen
readers
Enable copying of text,
images, and other content
Allowed change level
Allowed printing level
Disable document
modification
Permission available when
"Encryption level" is set to 0.
When set to "true", the PDF file
cannot be edited.
false
pdf-no-changingthe-document
Disable printing
Permission available when
"Encryption level" is set to 0.
When set to "true", printing is
disabled for the PDF file.
false
pdf-no-printing
Disable adding or
changing comments
and form fields
Permission available when
"Encryption level" is set to 0.
When set to "true", the ability to
add or change comments and
form fields is disabled.
false
pdf-no-accff
Disable context
copying, extraction,
and accessibility
Permission available when
"Encryption level" is set to 0.
When set to "true", the context
copying, extraction, and
accessibility features are
disabled.
false
pdf-no-cceda
11-3
Chapter 11
PDF Output Properties
Property Name
Description
Default
Internal Name
Enable text access for
screen readers
Permission available when
"Encryption level" is set to 1 or
higher. When set to "true", text
access for screen reader devices
is enabled.
true
pdf-enableaccessibility
Enable copying of text, Permission available when
false
images, and other
"Encryption level" is set to 1 or
content
higher. When set to "true",
copying of text, images, and other
content is enabled.
pdf-enable-copying
Allowed change level
0
pdf-changesallowed
0
pdf-printingallowed
Permission available when
"Encryption level" is set to 1 or
higher. Valid Values are:
•
•
•
•
•
Allowed printing level
0: none
1: Allows inserting, deleting,
and rotating pages
2: Allows filling in form fields
and signing
3: Allows commenting, filling
in form fields, and signing
4: Allows all changes except
extracting pages
Permission available when
"Encryption level" is set to 1 or
higher. Valid values are:
•
•
•
0: None
1: Low resolution (150 dpi)
2: High resolution
Use only one shared
The default mode of BI Publisher true
resources object for all creates one shared resources
pages
object for all pages in a PDF file.
This mode has the advantage of
creating an overall smaller file
size. However, the disadvantages
are the following:
pdf-use-oneresources
•
Viewing may take longer for
a large file with many SVG
objects
•
If you choose to break up the
file by using Adobe Acrobat
to extract or delete portions,
then the edited PDF files are
larger because the single
shared resource object (that
contains all of the SVG
objects for the entire file) is
included with each extracted
portion.
Setting this property to "false"
creates a resource object for each
page. The file size is larger, but
the PDF viewing is faster and the
PDF can be broken up into
smaller files more easily.
11-4
Chapter 11
PDF Digital Signature Properties
Property Name
Description
PDF Navigation Panel
Initial View
Controls the navigation panel
Bookmarks
view that is presented when a
Open
user first opens a PDF report. The
following options are supported:
•
•
•
Default
Internal Name
pdf-pagemode
Panels Collapsed - displays
the PDF document with the
navigation panel collapsed.
Bookmarks Open (default) displays the bookmark links
for easy navigation.
Pages Open - displays a
clickable thumbnail view of
each page of the PDF.
PDF Digital Signature Properties
There are specific properties that should only be set at the report level to enable digital
signature for a report and to define the placement of the signature in the output PDF
document.
For more information on how to enable digital signature for your output PDF
documents, see Implementing a Digital Signature.
Note that to implement digital signature for a report based on a PDF layout template or
an RTF layout template, you must set the property Enable Digital Signature to "True"
for the report.
You also must set the appropriate properties to place the digital signature in the
desired location on your output report. Your choices for placement of the digital
signature depend on the template type. The choices are as follows:
•
(PDF only) Place the digital signature in a specific field by setting the Existing
signature field name property.
•
(RTF and PDF) Place the digital signature in a general location of the page (top
left, top center, or top right) by setting the Signature field location property.
•
(RTF and PDF) Place the digital signature in a specific location designated by x
and y coordinates by setting the Signature field x coordinate and Signature
field y coordinate properties.
If you choose this option, you can also set Signature field width and Signature
field height to define the size of the field in your document.
Property Name
Description
Default
Internal
Name
Enable Digital
Signature
Set this to "true" to enable digital
signature for the report.
false
signatureenable
11-5
Chapter 11
PDF Digital Signature Properties
Property Name
Description
Default
Existing signature
field name
This property applies to PDF layout
N/A
templates only. If the report is based
on a PDF template, then you can enter
a field from the PDF template in which
to place the digital signature.
Internal
Name
signaturefield-name
For more information about defining a
field for the signature in a PDF
template, see Adding or Designating a
Field for a Digital Signature in Report
Designer's Guide for Oracle Business
Intelligence Publisher.
Signature field
location
This property can apply to RTF or PDF N/A
layout templates. This property
provides a list that contains the
following values: Top Left, Top Center,
Top Right. Choose one of these
general locations and BI Publisher
inserts the digital signature to the
output document, sized and positioned
appropriately. If you choose to set this
property, do not enter X and Y
coordinates or width and height
properties.
signaturefieldlocation
Signature field X
coordinate
This property can apply to RTF or PDF 0
layout templates. Using the left edge of
the document as the zero point of the
X axis, enter the position in points that
you want the digital signature to be
placed from the left. For example, if
you want the digital signature to be
placed horizontally in the middle of an
8.5 inch by 11 inch document (that is,
612 points in width and 792 points in
height), enter 306.
signaturefield-pos-x
Signature field Y
coordinate
This property can apply to RTF or PDF 0
layout templates. Using the bottom
edge of the document as the zero point
of the Y axis, enter the position in
points that you want the digital
signature to be placed from the
bottom. For example, if you want the
digital signature to be placed vertically
in the middle of an 8.5 inch by 11 inch
document (that is, 612 points in width
and 792 points in height), enter 396.
signaturefield-pos-y
Signature field width
Enter in points (72 points equal one
0
inch) the desired width of the inserted
digital signature field. This applies only
if you are also setting the Signature
field x coordinate and Signature
field Y coordinate properties..
signaturefield-width
11-6
Chapter 11
PDF/A Output Properties
Property Name
Description
Default
Signature field height
Enter in points (72 points equal one
0
inch) the desired height of the inserted
digital signature field. This applies only
if you are also setting the Signature
field x coordinate and Signature
field Y coordinate properties.
Internal
Name
signaturefield-height
PDF/A Output Properties
Set the properties described in the table below to configure PDF/A output.
For more information on PDF/A output, see Generating PDF/A and PDF/X Output in
Report Designer's Guide for Oracle Business Intelligence Publisher.
Property Name
Description
Default
Internal Name
PDF/A ICC Profile
Data
The name of the ICC profile data file,
for example: CoatedFOGRA27.icc
Default profile
data provided
by JVM
pdfa-iccprofile-data
ICC profile information (required when
pdfa-icc-profile-data is specified)
sRGB
IEC61966-2.1
pdfa-iccprofile-info
PDF/A file identifier One or more valid file identifiers set in
the xmpMM:Identifier field of the
metadata dictionary. To specify more
than one identifier, separate values
with a comma (,).
Automatically
generated file
identifier
pdfa-fileidentifier
PDF/A document ID Valid document ID. The value is set in
the xmpMM:DocumentID field of the
metadata dictionary.
None
pdfadocument-id
The ICC (International Color
Consortium) profile is a binary file
describing the color characteristics of
the environment where this PDF/A file
is intended to be displayed.
The ICC profile that you select must
have a major version below 4.
To use a specific profile data file other
than the default settings in the JVM,
obtain the file and place it under <bi
publisher repository>/Admin/
Configuration. When you set this
property, you must also set a value for
PDF/A ICC Profile Info (pdfa-iccprofile-info).
PDF/A ICC Profile
Info
PDF/A version ID
Valid version ID. The value is set in the None
xmpMM:VersionID field of the
metadata dictionary.
pdfa-versionid
PDF/A rendition
class
Valid rendition class. The value is set
in the xmpMM:RenditionClass field of
the metadata dictionary.
pdfarenditionclass
None
11-7
Chapter 11
PDF/X Output Properties
PDF/X Output Properties
Configure PDF/X output by setting the properties described below. The values that you
set for these properties will depend on the printing device.
Note the following restrictions on other PDF properties:
•
pdf-version — Value above 1.4 is not allowed for PDF/X-1a output.
•
pdf-security — Must be set to False.
•
pdf-encryption-level — Must be set to 0.
•
pdf-font-embedding — Must be set to true.
See Generating PDF/A and PDF/X Output in Report Designer's Guide for Oracle
Business Intelligence Publisher.
Property Name
Description
Default
Internal Name
PDF/X ICC Profile
Data
(Required) The name of the ICC
profile data file, for example:
CoatedFOGRA27.icc.
None
pdfx-dest-outputprofile-data
The ICC (International Color
Consortium) profile is a binary file
describing the color
characteristics of the intended
output device. For production
environments, the color profile
may be provided by your print
vendor or by the printing company
that prints the generated PDF/X
file. The file must be placed under
<bi publisher repository>/
Admin/Configuration.
Profile data is also available from
Adobe support or
colormanagement.org.
PDF/X output
condition identifier
(Required) The name of one of
None
the standard printing conditions
registered with ICC (International
Color Consortium). The value that
you enter for this property is a
valid "Reference name," for
example: FOGRA43.
pdfx-outputconditionidentifier
Choose the appropriate value for
the intended printing environment.
This name is often used to guide
automatic processing of the file by
the consumer of the PDF/X
document, or to inform the default
settings in interactive applications.
11-8
Chapter 11
DOCX Output Properties
Property Name
Description
Default
PDF/X output
condition
A string describing the intended
None
printing condition in a form that
will be meaningful to a human
operator at the site receiving the
exchanged file. The value is set in
OutputCondition field of
OutputIntents dictionary.
Internal Name
pdfx-outputcondition
PDF/X registry name A registry name. Set this property http://
when the pdfx-outputwww.color.org
condition-identifier is set to a
characterization name that is
registered in a registry other than
the ICC registry.
pdfx-registryname
PDF/X version
pdfx-version
The PDF/X version set in
PDF/X-1a:
GTS_PDFXVersion and
2003
GTS_PDFXConformance fields of
Info dictionary. PDF/X-1a:2003 is
the only value currently
supported.
DOCX Output Properties
The table below describes the properties that control DOCX output files.
Property Name
Description
Enable change
tracking
Set to "true" to enable change false
tracking in the output
document.
Protect document for Set to "true" to protect the
tracked changes
document for tracked
changes.
Default font
Default
false
Use this property to define the Arial:12
font style and size in the
output when no other font has
been defined. This is
particularly useful to control
the sizing of empty table cells
in generated reports. Enter
the font name and size in the
following format
<FontName>:<size> for
example: Arial:12. Note that
the font you choose must be
available to the BI Publisher
processing engine at runtime.
See Defining Font Mappings
for information about installing
fonts for the BI Publisher
server and also for the list of
fonts predefined for BI
Publisher.
Internal Name
docx-trackchanges
docx-protectdocument-fortracked-changes
docx-outputdefault-font
11-9
Chapter 11
RTF Output Properties
RTF Output Properties
Configure RTF output files by setting the properties described in the table below.
Property Name
Description
Default
Internal Name
Enable change
tracking
Set to "true" to enable change
tracking in the output RTF
document.
false
rtf-track-changes
false
rtf-protectdocument-fortracked-changes
Protect document
Set to "true" to protect the
for tracked changes document for tracked changes.
Default font
Use this property to define the
Arial:12
font style and size in RTF output
when no other font has been
defined. This is particularly useful
to control the sizing of empty
table cells in generated reports.
Enter the font name and size in
the following format
<FontName>:<size> for example:
Arial:12. Note that the font you
choose must be available to the
BI Publisher processing engine at
runtime. See Defining Font
Mappings for information about
installing fonts for the BI
Publisher server and also for the
list of fonts predefined for BI
Publisher.
rtf-outputdefault-font
HTML Output Properties
The table below describes the properties that control HTML output files.
Property Name
Description
Default
Internal Name
Show header
Set to "false" to suppress the
template header in HTML
output.
true
html-show-header
Show footer
Set to "false" to suppress the
template footer in HTML
output.
true
html-show-footer
Replace smart
quotes
Set to "false" if you do not
want curly quotes replaced
with straight quotes in the
HTML output.
true
html-replacesmartquotes
Character set
Specifies the output HTML
character set.
UTF-8
html-outputcharset
Make HTML
output accessible
Specify true if you want to
make the HTML output
accessible.
false
make-accessible
11-10
Chapter 11
FO Processing Properties
Property Name
Description
Default
Use percentage
width for table
columns
Set this property to true to
true
render table columns
according to a percentage
value of the total width of the
table rather than as a value in
points. This property is
especially useful if the
browser renders tables with
extremely wide columns.
Setting this property to true
improves the readability of the
tables.
View Paginated
When set to true, HTML
false
output will render in the report
viewer with pagination
features. These features
include:
Internal Name
html-outputwidth-inpercentage
•
Generated table of
contents
•
Navigation links at the top
and bottom of the page
•
Ability to skip to a specific
page within the HTML
document
•
Search for strings within
the HTML document
using the browser's
search capability
•
Zoom in and out on the
HTML document using
the browser's zoom
capability
Note that these features are
supported for online viewing
through the report viewer
only.
FO Processing Properties
The table below describes the properties that control FO processing.
Property Name
Description
Default
Internal Name
Use BI Publisher's
XSLT processor
Controls BI Publisher's
true
parser usage. If set to false,
then XSLT is not parsed.
xslt-xdoparser
Enable scalable
feature of XSLT
processor
Controls the scalable
false
feature of the XDO parser.
The property "Use BI
Publisher's XSLT
processor" must be set to
"true" for this property to be
effective.
xslt-scalable
11-11
Chapter 11
FO Processing Properties
Property Name
Description
Default
Internal Name
Enable XSLT
runtime
optimization
When set to "true", the
true
overall performance of the
FO processor is increased
and the size of the
temporary FO files
generated in the temp
directory is significantly
decreased. Note that for
small reports (for example
1-2 pages) the increase in
performance is not as
marked. To further enhance
performance when you set
this property to true, it is
recommended that you set
the Extract attribute sets
property to "false". See RTF
Template Properties.
xslt-runtimeoptimization
Enable XPath
Optimization
When set to "true", the XML false
data file is analyzed for
element frequency. The
information is then used to
optimize XPath in XSL.
xslt-xpathoptimization
Pages cached
during processing
This property is enabled
50
only when you have
specified a Temporary
Directory (under General
properties). During table of
contents generation, the FO
Processor caches the
pages until the number of
pages exceeds the value
specified for this property. It
then writes the pages to a
file in the Temporary
Directory.
system-cache-pagesize
Bidi language digit
substitution type
Valid values are "None" and National
"National". When set to
"None", Eastern European
numbers are used. When
set to "National", Hindi
format (Arabic-Indic digits)
is used. This setting is
effective only when the
locale is Arabic, otherwise it
is ignored.
digit-substitution
Disable variable
header support
If "true", prevents variable
false
header support. Variable
header support
automatically extends the
size of the header to
accommodate the contents.
fo-preventvariable-header
11-12
Chapter 11
FO Processing Properties
Property Name
Description
Default
Internal Name
Add prefix to IDs
when merging FO
When merging multiple
XSL-FO inputs, the FO
Processor automatically
adds random prefixes to
resolve conflicting IDs.
Setting this property to
"true" disables this feature.
false
fo-merge-conflictresolution
Enable
multithreading
If you have a multiprocessor false
machine or a machine with
a dual-core single
processor, you may be able
to achieve faster document
generation by setting this
option to True.
fo-multi-threads
Disable external
references
A "true" setting (default)
true
disallows the importing of
secondary files such as
subtemplates or other XML
documents during XSL
processing and XML
parsing. This increases the
security of the system. Set
this to "false" if the report or
template calls external files.
xdk-secure-io-mode
FO Parsing Buffer
Size
Sets the size of the buffer
1000000
for the FO Processor. When
the buffer is full, the
elements from the buffer are
rendered in the report.
Reports with large tables or
pivot tables that require
complex formatting and
calculations may require a
larger buffer to properly
render those objects in the
report. Increase the size of
the buffer at the report level
for these reports. Note that
increasing this value affects
the memory consumption of
the system.
fo-chunk-size
11-13
Chapter 11
RTF Template Properties
Property Name
Enable XSLT
runtime
optimization for
sub-template
Description
Default
Internal Name
true
xslt-do-import
Note:
The default is true on the BI
Publisher server. If you call
the FOProcessor directly,
the default is false.
Provides an option to
perform XSL import in
FOProcessor before
passing only one XSL to
XDK for further processing.
This allows xslt-optimization
to be applied to the entire
main XSL template which
already includes all its
subtemplates.
Enable PPTX
native chart
support
This property applies to
false
PowerPoint 2007 output.
When set to true, charts in
PowerPoint 2007 output are
rendered as native
PowerPoint (PPTX) charts.
When set to false, the chart
is rendered as an
embedded PNG image.
pptx-native-chart
Report Timezone
Valid values: User or JVM.
fo-report-timezone
User
When set to User, BI
Publisher uses the Userlevel Report Time Zone
setting for reports. The User
Report Time Zone is set in
the user's Account Settings.
When set to JVM, BI
Publisher uses the server
JVM timezone setting for all
users' reports. All reports
therefore display the same
time regardless of individual
user settings. This setting
can be overridden at the
report level.
RTF Template Properties
Configure RTF templates by setting the properties described in the table below.
11-14
Chapter 11
PDF Template Properties
Property Name
Description
Default
Internal Name
Extract attribute sets
The RTF processor automatically
extracts attribute sets within the
generated XSL-FO. The extracted
sets are placed in an extra FO
block, which can be referenced.
This improves processing
performance and reduces file size.
Valid values are:
Auto
rtf-extractattribute-sets
true
rtf-rewrite-path
•
•
•
Enable - extract attribute sets
for all templates and
subtemplates
Auto - extract attribute sets for
templates, but not
subtemplates
Disable - do not extract
attribute sets
Enable XPath
rewriting
When converting an RTF template
to XSL-FO, the RTF processor
automatically rewrites the XML tag
names to represent the full XPath
notations. Set this property to
"false" to disable this feature.
Characters used for
checkbox
The BI Publisher default PDF
Albany WT J;
output font does not include a glyph 9746;9747/A
to represent a checkbox. If the
template contains a checkbox, use
this property to define a Unicode
font for the representation of
checkboxes in the PDF output. You
must define the Unicode font
number for the "checked" state and
the Unicode font number for the
"unchecked" state using the
following syntax:
fontname;<unicode font number
for true value's glyph
>;<unicode font number for
false value's glyph>
rtf-checkboxglyph
Example: Albany WT J;
9746;9747/A Note that the font that
you specify must be made
available to BI Publisher at runtime.
PDF Template Properties
Generate the types of PDF files you want by setting available PDF template
properties.
See Setting Fields as Updatable or Read Only and Creating PDF Templates in Report
Designer's Guide for Oracle Business Intelligence Publisher.
11-15
Chapter 11
Flash Template Properties
Property Name
Description
Default
Internal Name
Remove PDF fields
from output
Specify "true" to remove PDF false
fields from the output. When
PDF fields are removed, data
entered in the fields cannot
be extracted.
remove-pdf-fields
Set all fields as read
only in output
By default, BI Publisher sets true
all fields in the output PDF of
a PDF template to be read
only. If you want to set all
fields to be updatable, set
this property to "false".
all-field-readonly
Maintain each field's
read only setting
Set this property to "true" if
false
you want to maintain the
"Read Only" setting of each
field as defined in the PDF
template. This property
overrides the settings of "Set
all fields as read only in
output."
all-fieldsreadonly-asis
Flash Template Properties
The table below describes the properties that control Flash templates.
Property Name
Description
Default
Internal Name
Page width of
wrapper document
Specify in points the width
of the output PDF
document. The default is
792, or 11 inches.
792
flash-page-width
Page height of
wrapper document
Specify in points the height
of the output PDF
document. The default is
612, or 8.5 inches.
612
flash-page-height
Start x position of
Flash area in PDF
Using the left edge of the
document as the 0 axis
point, specify in points the
beginning horizontal
position of the Flash object
in the PDF document. The
default is 18, or .25 inch.
18
flash-startx
Start y position of
Flash area in PDF
Using the upper left corner
of the document as the 0
axis point, specify in points
the beginning vertical
position of the Flash object
in the PDF document. The
default is 18, or .25 inch.
18
flash-starty
11-16
Chapter 11
CSV Output Properties
Property Name
Description
Default
Internal Name
Width of Flash area
Enter in points the width of Same as flash
flash-width
the area in the document for width in points in
the Flash object to occupy. swf
The default is the width of
the SWF object.
Height of Flash area
Enter in points the height of Same as flash
the area in the document for height in points
the Flash object to occupy. in swf
The default is the height of
the SWF object.
flash-height
CSV Output Properties
The table below describes the properties that control comma-delimited value output.
Property Name
Description
Default
CSV delimiter
Specifies the character used to delimit ,
the data in comma-separated value
output. Other options are: Semicolon
(;), Tab (\t) and Pipe (|).
Remove leading and
trailing white space
Specify "True" to remove leading and false
trailing white space between data
elements and the delimiter.
Excel 2007 Output Properties
You can set specific properties to control Excel 2007 output.
Property Name
Description
Default
Show grid lines
Set to true to show the Excel table grid lines in the false
report output.
Page break as a new
sheet
When set to "True" a page break that is specified
in the report template generates a new sheet in
the Excel workbook.
true
Minimum column
width
When the column width is less than the specified
minimum and it contains no data, the column is
merged with the preceding column. The value
must be set in points. The valid range for this
property is 0.5 to 20 points.
3 (in points, 0.04
inch)
Minimum row height
When the row height is less than the specified
minimum and it contains no data, the row is
removed. The value must be set in points. The
valid range for this property is .001 to 5 points.
1 (in points, 0.01
inch)
Keep values in same
column
Set this property to True to minimize column
merging. Column width is set based on column
contents using the values supplied in the Table
Auto Layout property. Output may not appear as
neatly laid out as when using the original layout
algorithm.
False
11-17
Chapter 11
All Outputs Properties
Property Name
Description
Default
Table Auto Layout
Specify a conversion ratio in points and a
maximum length in points, for example 6.5,150.
See example.
N/A
For this property to take effect, the property "Keep
values in same column" must be set to True.
This property expands the table column width to fit
the contents. The column width is expanded
based on the character count and conversion ratio
up to the maximum specification.
Example: Assume a report with two columns of
Excel data -- Column 1 contains a text string that
is 18 characters and Column 2 is 30 characters
long. When the value of this property is set to
6.5,150, the following calculations are performed:
Column 1 is 18 characters:
Apply the calculation: 18 * 6.5pts = 117 pts
The column in the Excel output will be 117 pts
wide.
Column 2 is 30 characters:
Apply the calculation: 30 * 6.5 pts = 195 pts
Because 195 pts is greater than the specified
maximum of 150, Column 2 will be 150 pts wide in
the Excel output.
Maximum allowable
nested table row
count
Specify the maximum allowable row count for a
nested table. Allowed values are 15000 to
999,999.
20,000
During report processing, nested inner table rows
cannot be flushed to the XLSX writer, therefore
they stay in-memory, increasing memory
consumption. Set this limit to avoid out-of-memory
exceptions. When this limit is reached for the size
of the inner table, generation is terminated. The
incomplete XLSX output file is returned.
All Outputs Properties
The properties in the table below apply to all outputs.
Property Name
Description
Default
Hide version number
in output
Some report output documents display
Oracle BI Publisher in the document
properties. For example, PDF
documents identify Oracle BI Publisher
as the PDF Producer in the properties
for the document. If you do not want to
include the version of BI Publisher that
generated the document then set this
property to true.
false
Use 11.1.1.5
compatibility mode
Reserved. Do not update unless
instructed by Oracle.
11-18
Chapter 11
Memory Guard & Data Model Properties
Memory Guard & Data Model Properties
Memory guard safeguards your system against memory failures caused by report
requests that generate excessive data.
Memory guard and data model properties are described in Enabling Memory Guard
Features.
Defining Font Mappings
BI Publisher's Font Mapping feature enables you to map base fonts in RTF or PDF
templates to target fonts to be used in the published document.
Font Mappings can be specified at the site or report level. Font mapping is performed
only for PDF output and PowerPoint output.
There are two types of font mappings:
•
RTF Templates — for mapping fonts from RTF templates and XSL-FO templates
to PDF and PowerPoint output fonts
•
PDF Templates — for mapping fonts from PDF templates to different PDF output
fonts.
Making Fonts Available to BI Publisher
BI Publisher provides a set of Type1 fonts and a set of TrueType fonts. You can select
any of the fonts in these sets as a target font with no additional setup required.
For a list of the predefined fonts see BI Publisher Predefined Fonts.
The predefined fonts are located in $MW_HOME/oracle_common/internal/fonts.
To map to another font, place the font in this directory to make it available to BI
Publisher at runtime. If the environment is clustered, then you must place the font on
every server.
Setting Font Mapping at the Site Level or Report Level
A font mapping can be defined at the site level or the report level.
•
To set a mapping at the site level, select the Font Mappings link from the
Administration page.
•
To set a mapping at the report level, view the Properties for the report, then select
the Font Mappings tab. These settings apply to the selected report only.
The report-level settings take precedence over the site-level settings.
Creating a Font Mapping
From the Administration page, under Runtime Configuration, select Font Mappings.
To create a Font Mapping:
1.
Under RTF Templates or PDF Templates, select Add Font Mapping.
11-19
Chapter 11
Defining Font Mappings
2.
Enter the following on the Add Font Mapping page:
•
Base Font — enter the font family to map to a new font. Example: Arial
•
Select the Style: Normal or Italic (Not applicable to PDF Template font
mappings)
•
Select the Weight: Normal or Bold (Not applicable to PDF Template font
mappings)
•
Select the Target Font Type: Type 1 or TrueType
•
Enter the Target Font
If you selected TrueType, you can enter a specific numbered font in the
collection. Enter the TrueType Collection (TTC) Number of the desired font.
For a list of the predefined fonts see BI Publisher Predefined Fonts.
BI Publisher Predefined Fonts
The following Type1 fonts are built-in to Adobe Acrobat and BI Publisher provides a
mapping for these fonts by default.
You can select any of these fonts as a target font with no additional setup required.
The Type1 fonts are listed in the table below.
Number
Font Family
Style
Weight
Font Name
1
serif
normal
normal
Time-Roman
1
serif
normal
bold
Times-Bold
1
serif
italic
normal
Times-Italic
1
serif
italic
bold
Times-BoldItalic
2
sans-serif
normal
normal
Helvetica
2
sans-serif
normal
bold
Helvetica-Bold
2
sans-serif
italic
normal
Helvetica-Oblique
2
sans-serif
italic
bold
Helvetica-BoldOblique
3
monospace
normal
normal
Courier
3
monospace
normal
bold
Courier-Bold
3
monospace
italic
normal
Courier-Oblique
3
monospace
italic
bold
Courier-BoldOblique
4
Courier
normal
normal
Courier
4
Courier
normal
bold
Courier-Bold
4
Courier
italic
normal
Courier-Oblique
4
Courier
italic
bold
Courier-BoldOblique
5
Helvetica
normal
normal
Helvetica
5
Helvetica
normal
bold
Helvetica-Bold
5
Helvetica
italic
normal
Helvetica-Oblique
5
Helvetica
italic
bold
Helvetica-BoldOblique
6
Times
normal
normal
Times
11-20
Chapter 11
Defining Font Mappings
Number
Font Family
Style
Weight
Font Name
6
Times
normal
bold
Times-Bold
6
Times
italic
normal
Times-Italic
6
Times
italic
bold
Times-BoldItalic
7
Symbol
normal
normal
Symbol
8
ZapfDingbats
normal
normal
ZapfDingbats
The TrueType fonts are listed in the table below. All TrueType fonts are subset and
embedded into PDF.
Number
Font Family
Name
Style
Weight
Actual Font
Actual Font Type
1
Albany WT
normal
normal
ALBANYWT.ttf
TrueType (Latin1
only)
2
Albany WT J
normal
normal
ALBANWTJ.ttf
TrueType
(Japanese flavor)
3
Albany WT K
normal
normal
ALBANWTK.ttf
TrueType (Korean
flavor)
4
Albany WT SC
normal
normal
ALBANWTS.ttf
TrueType
(Simplified
Chinese flavor)
5
Albany WT TC
normal
normal
ALBANWTT.ttf
TrueType
(Traditional
Chinese flavor)
6
Andale
Duospace WT
normal
normal
ADUO.ttf
TrueType (Latin1
only, Fixed width)
6
Andale
Duospace WT
bold
bold
ADUOB.ttf
TrueType (Latin1
only, Fixed width)
7
Andale
normal
Duospace WT J
normal
ADUOJ.ttf
TrueType
(Japanese flavor,
Fixed width)
7
Andale
bold
Duospace WT J
bold
ADUOJB.ttf
TrueType
(Japanese flavor,
Fixed width)
8
Andale
normal
Duospace WT K
normal
ADUOK.ttf
TrueType (Korean
flavor, Fixed width)
8
Andale
bold
Duospace WT K
bold
ADUOKB.ttf
TrueType (Korean
flavor, Fixed width)
9
Andale
Duospace WT
SC
normal
normal
ADUOSC.ttf
TrueType
(Simplified
Chinese flavor,
Fixed width)
9
Andale
Duospace WT
SC
bold
bold
ADUOSCB.ttf
TrueType
(Simplified
Chinese flavor,
Fixed width)
11-21
Chapter 11
Defining Currency Formats
Number
Font Family
Name
Style
Weight
Actual Font
Actual Font Type
10
Andale
Duospace WT
TC
normal
normal
ADUOTC.ttf
TrueType
(Traditional
Chinese flavor,
Fixed width)
10
Andale
Duospace WT
TC
bold
bold
ADUOTCB.ttf
TrueType
(Traditional
Chinese flavor,
Fixed width)
Managing Custom Fonts
BI Publisher includes a standard set of fonts. Using manage custom fonts you can
upload external fonts apart from the BI Publisher's inbuilt fonts.
To manage custom fonts
1.
Navigate to the Manage Custom Fonts section in Administration > Font Mappings
page.
2.
Click Choose File and select the external font file.
You have the option to either overwrite or delete the font files.
3.
To use the new font, define the font mapping for RTF or PDF template. See
Defining Font Mappings.
Defining Currency Formats
Currency formats defined in the Administration Runtime Configuration page are
applied at the system level. Currency formats can also be applied at the report level.
The report-level settings take precedence over the system-level settings here. For
information on setting a report-level currency format, see Configuring Currency
Formats in Report Designer's Guide for Oracle Business Intelligence Publisher.
Understanding Currency Formats
The Currency Formats tab enables you to map a number format mask to a specific
currency so that your reports can display multiple currencies with their own
corresponding formatting. Currency formatting is only supported for RTF and XSL-FO
templates.
To apply these currency formats in the RTF template, use the format-currency
function. See Formatting Currencies and Using the Oracle Format Mask in Report
Designer's Guide for Oracle Business Intelligence Publisher .
To add a currency format:
1.
Click the Add icon.
2.
Enter the ISO currency code, for example: USD, JPY, EUR, GBP, INR.
3.
Enter the format mask to apply for this currency.
11-22
Chapter 11
Defining Currency Formats
The Format Mask must be in the Oracle number format. The Oracle number
format uses the components "9", "0", "D", and "G" to compose the format, for
example: 9G999D00
where
9 represents a displayed number only if present in data
G represents the group separator
D represents the decimal separator
0 represents an explicitly displayed number regardless of incoming data
The figure below shows sample currency formats.
11-23
12
Diagnostics and Performance Monitoring
This chapter describes configuring log files for diagnosing issues in BI Publisher and
configuring user auditing to capture metrics on user activity and system performance.
It covers the following topics:
•
Diagnosing and Resolving Issues in Oracle BI Publisher
•
About Diagnostic Log Files
•
Configuring Log Files
•
Enabling Scheduler Job Diagnostics
•
Viewing Log Messages
•
About Performance Monitoring and User Auditing
•
Enabling Monitoring and Auditing
•
Viewing the Audit Log
•
Using BI Publisher to Create Audit Reports
•
Viewing Performance Statistics in DMS Spy
•
Viewing Performance Statistics in the MBean Browser
Diagnosing and Resolving Issues in Oracle BI Publisher
System administrators are typically responsible for supporting end users when they
experience issues with the use of Oracle BI Publisher and for interacting with Oracle
Support to understand the cause of issues and apply fixes.
Issues may be reported in response to end users receiving error messages,
experiencing poor performance, or lack of availability.
The principal activities administrators perform to support issue resolution include:
•
•
Examination of error and diagnostic log information. For more information, see:
–
About Diagnostic Log Files
–
Configuring Log Files
–
Viewing Log Messages
Examination of system and process metrics to understand availability and
performance issues. For more information, see:
–
About Performance Monitoring and User Auditing
–
Enabling Monitoring and Auditing
–
Viewing the Audit Log
–
Using BI Publisher to Create Audit Reports
–
Viewing Performance Statistics in DMS Spy
12-1
Chapter 12
About Diagnostic Log Files
–
Viewing Performance Statistics in the MBean Browser
About Diagnostic Log Files
BI Publisher writes diagnostic log files in the Oracle Diagnostic Logging (ODL) format.
Log file naming and the format of the contents of log files conform to an Oracle
standard. You can view log files by using the WLST displayLogs command, or you can
download log files to your local client and view them using another tool (for example a
text editor, or another file viewing utility).
Log files are created and edited using Oracle Fusion Middleware Control. By default,
after installation, the bipublisher-handler log is created. You can configure this log file
or create a new logger.
About Log File Message Categories and Levels
Each log file message category is set to a specific default value between 1-32, and
only messages with a level less or equal to the log level are logged.
Various log file message categories exist, as described in the table below.
Level
Description
IncidentError:1
A serious problem caused by unknown reasons. You can only fix the
problem by contacting Oracle support. Examples are errors from which
you cannot recover or serious problems.
Error:1
A problem requiring attention from the system administrator has
occurred, and is not caused by a bug in the product. No performance
impact.
Warning:1
A potential problem that should be reviewed by the administrator.
Examples are invalid parameter values or a specified file does not exist.
Notification:1
A major lifecycle event such as the activation or deactivation of a
primary sub-component or feature. This is the default level for
NOTIFICATION.
NOTIFICATION:16
A finer level of granularity for reporting normal events.
TRACE:1
Trace or debug information for events that are meaningful to
administrators, such as public API entry or exit points.
TRACE:16
Detailed trace or debug information that can help Oracle Support
diagnose problems with a particular subsystem.
TRACE:32
Very detailed trace or debug information that can help Oracle Support
diagnose problems with a particular subsystem.
About Log File Formats
A log file must contain a consistent format.
However, since there can be multiple formats, you can change the format used in a log
file. When you change the format used in a log file, and the new format differs from the
current log file's format, a new log file is created. For example, a log file that contains
ODL-XML, always contains XML, and is never mixed with text.
12-2
Chapter 12
Configuring Log Files
Configure the log file format in the Edit Log File dialog. See Configuring Log Files. The
format can by Text or XML.
About Log File Rotation
Log file rotation can be file size based or time based.
Whenever a log file exceeds the rotation criterion, the existing log file is renamed, and
a new log file is created.
The file naming looks like this:
•
log.xml
•
log.xml.1 (oldest log file)
•
log.xml.n
Configuring Log Files
Use Oracle Fusion Middleware Control to configure BI Publisher log files.
See the following topics:
•
Setting the Log Level
•
Configuring Other Log File Options
Setting the Log Level
You can set the log level in Oracle Fusion Middleware Control.
To set the log level in Oracle Fusion Middleware Control:
1.
In Oracle Fusion Middleware Control, locate the BI Publisher server. For example:
Under Application Deployments, expand bipublisher (11.1.1.) (bi_cluster), and
then right-click bipublisher (11.1.1)(bi_server1).
2.
From the menu, click Logs and then Log Configuration.
3.
In the Log Levels tab, under Logger Name, expand Root Logger, then expand
oracle.
Locate oracle.xdo and select the log level from the drop-down list.
4.
Click Apply.
Configuring Other Log File Options
You configure log files in Oracle Fusion Middleware Control.
To configure log files:
1.
Navigate to the Log Configuration page as described in Setting the Log Level.
2.
Select the Log Files tab.
3.
Select bipublisher-handler in the table and click Edit Configuration.
4.
In the Edit Log File dialog, configure the bipublisher-handler log file options. A
sample is shown below.
12-3
Chapter 12
Enabling Scheduler Job Diagnostics
Enabling Scheduler Job Diagnostics
You can enable job diagnostics in the Diagnostics tab in the Schedule Report Job
page, and download the job diagnostic logs from Report Job History.
You must have BI Administrator or BI Data Model Developer privileges to access the
Diagnostics tab in the Schedule Report Job page. Perform the following steps to
enable job diagnostics.
1.
From the New menu, select Report Job.
2.
Select the report to schedule, and click the Diagnostics tab.
3.
Select and enable the required diagnostics.
Option
Description
Enable SQL Explain Plan
Generates a diagnostic log with Explain plan/SQL
monitor report information.
Enable Data Engine Diagnostic
Generates a data processor log.
Enable Report Processor Diagnostic Generates FO (Formatting Options) and server
related log information.
Enable Consolidated Job Diagnostic Generates the entire log, which includes scheduler
log, data processor log, FO and server log details.
You can download the job diagnostic logs from Report Job History, and view the
details.
12-4
Chapter 12
Viewing Log Messages
Viewing Log Messages
You can view log messages using Oracle Fusion Middleware Control or you can view
the log files directly.
To view log messages in Oracle Fusion Middleware Control:
1.
In Oracle Fusion Middleware Control, locate the BI Publisher server. For example:
Under Application Deployments, right-click bipublisher (11.1.1).
2.
From the menu, click Logs and View Log Messages.
3.
To view a specific log file, click Target Log Files.
4.
From the Log Files page, select a specific log to view messages or download the
log file.
5.
Click View Log File to view the messages.
Viewing Messages by Reading the Log File
The log file is located in the directory that is specified in the Log Path in the Edit Log
File dialog. Navigate to the directory on the server to view the log file.
The following example shows an ODL format error message:
<msg time="2009-07-30T16:00:03.150-07:00" comp_id="xdo" type="ERROR" level="1"
host_id="MyBIPHost" host_addr="122.22.222.22" module="oracle.xdo" tid="11"
user="Administrator">
<txt>Variable 'G_dept' is missing...</txt>
</msg>
The table below describes the message attributes displayed in the log file:
Attribute Description
Name
time
The date and time when the message was generated. This reflects the local time
zone.
comp_id
The ID of the component that originated the message.
type
The type of message. Possible values are: INCIDENT_ERROR, ERROR,
WARNING, NOTIFICATION, TRACE, and UNKNOWN. See About Log File
Message Categories and Levels for information about the message types.
level
The message level, represented by an integer value that qualifies the message
type. Possible values are from 1 (highest severity) through 32 (lowest severity).
host_id
The name of the host where the message originated.
host_addr The network address of the host where the message originated.
module
The ID of the module that originated the message. If the component is a single
module, the component ID is listed for this attribute.
tid
The ID of the thread that generated the message.
user
The name of the user whose execution context generated the message.
12-5
Chapter 12
About Performance Monitoring and User Auditing
About Performance Monitoring and User Auditing
Performance monitoring enables you to monitor the performance of queries, reports
and document generation and to analyze the provided details.
BI Publisher collects performance statistics through Oracle Dynamic Monitoring
Service (DMS). You can monitor the performance data by using the DMS Spy servlet
provided by DMS on Enterprise Manager at http://
server_address:enterprise_manager_port/dms/Spy. BI Publisher also provides MBeans
that reveal attributes, operations, and relevant statistics gathered by DMS. The table
below summarizes the beans that are provided.
Management Bean
Description
ReportEventMonitor
Creates an Mbean per report and displays detailed
monitoring data for the report.
ServerEventMonitor
Exists per server and displays user and server activity
summaries.
UserEventMonitor
Creates an Mbean per user and displays detailed monitoring
data for the user.
Enabling Monitoring and Auditing
You enable monitoring and auditing on the Administration Server Configuration page
To enable monitoring and editing:
1.
Enable Monitor and Audit on the Administration Server Configuration page. See
Enabling Monitor and Audit on the Server Configuration Page.
2.
Configure the Audit Policy Settings with Fusion Middleware Control (Enterprise
Manager). See Configuring the Audit Policy Settings.
3.
Restart WebLogic Server.
Enabling Monitor and Audit on the Server Configuration Page
You can turn on monitoring and auditing for the BI Publisher application.
To turn on monitoring and auditing
1.
Click the Administration link.
2.
Under System Maintenance, click Server Configuration.
3.
Under the Monitor and Audit region, select the Enable Monitor and Audit check
box.
Configuring the Audit Policy Settings
Configure Audit Policy settings in Oracle Fusion Middleware Control.
To configure the audit policy settings
12-6
Chapter 12
Enabling Monitoring and Auditing
1.
In Oracle Fusion Middleware Control, under WebLogic Domain, select Security,
and then Audit Registration and Policy.
The Audit Policy page displays the audited applications under the WebLogic
domain.
2.
From the Audit Component Name list, select BI Publisher Server.
3.
Set the Audit Level to enable auditing for BI Publisher. An example is shown in
the figure below.
Typically, set the Audit Level to Medium.
To customize the audit level for each event, select Custom from the Audit Level list.
This setting enables you to set the audit level for each event and apply filters. Select a
category (User Session, Report Access, Report Execution, Report Job, or Report
Access) to view the available events.
The events that are audited for the BI Publisher server are:
•
User Login
•
User Logout
•
Report Request
•
Scheduled Report Request
•
Report Republish
•
Report Data Download
•
Report Download
•
Report Data Process
•
Report Rendering
•
Report Delivery
•
Report Job Scheduled
12-7
Chapter 12
Viewing the Audit Log
•
Report Job Canceled
•
Report Job Deleted
•
Report Job Purged
•
Report Job Resumed
•
Report Job History Deleted
•
Report Job History Purged
•
Resource Created
•
Resource Updated
•
Resource Copied
•
Resource Deleted
•
Resource Renamed
Restarting WebLogic Server
Restart the WebLogic Serve instance.
You can do this using Oracle Fusion Middleware Control, or if you are running
Windows, you can select Stop BI Servers and then Start BI Servers from the Start
menu.
Viewing the Audit Log
You can view the audit log under the under the bipublisher folder under the WebLogic
Server BI server directory. ORACLE_HOME/user_projects/domains/bi/
servers/bi_server1/logs/auditlogs/bipublisher/audit_1_0.log.
You can also query the audit repository on database. You can create your own reports
using BI Publisher to analyze the data collected.
For more information on the reports provided by Audit Framework, see Securing
Applications with Oracle Platform Security Services.
In 12c release, when you configure the BI domain, an audit schema is created, a data
source is created, and the audit database is registered for your domain.
Using BI Publisher to Create Audit Reports
Once auditing is configured, you can use BI Publisher to create your own reports to
visualize your auditing data.
To create a report on your auditing data in BI Publisher:
1.
Register the data source in BI Publisher.
2.
Create a data model.
3.
Create the report.
12-8
Chapter 12
Using BI Publisher to Create Audit Reports
Registering the Data Source in BI Publisher
Register the audit data source (JNDI/JDBC connection) that you created in the
previous procedure as a JNDI data source in BI Publisher.
Because you created a JDBC connection registered as JNDI, you do not need to
create a new JDBC connection by typing the connection URL, username/password,
and so on. You can just register it using the JNDI name (for example: jdbc/AuditDB).
1.
Log in to BI Publisher with administrator privileges and click the Administration
link.
2.
Under Data Sources, click JNDI Connection, then click Add Data Source.
3.
Enter the Data Source Name and JNDI Name jdbc/AuditViewDataSource.
4.
Click Test Connection to ensure that the data source connection works.
5.
Add the appropriate roles to the data source so that the report developers and
consumers can view the reports built on this data source.
6.
Click Apply to save.
Creating a Data Model
Run SQL queries against the BIPUBLISHER_V view to create data models.
To create a data model from your auditing data source:
Note:
See Data Modeling Guide for Oracle Business Intelligence Publisher.
1.
On the global header, click New and then click Data Model.
2.
Set the Default Data Source to the audit JNDI data source.
3.
Click Data Sets and from the Create New menu select new SQL Query data set.
4.
Use the Query Builder to build a query or just type a SQL query against the
BIPUBLISHER_V view.
The following sample SQL query returns only BI Publisher audit data common to
all event types:
Select IAU_EVENTCATEGORY,
IAU_EVENTTYPE,
IAU_EVENTSTATUS,
to_char("IAU_TSTZORIGINATING", 'DD-MON-YYYY HH24:MI:SSxFF') as
IAU_DATETIME,
IAU_INITIATOR,
IAU_RESOURCE,
IAU_MESSAGETEXT
from BIPUBLISHER_V;
12-9
Chapter 12
Viewing Performance Statistics in DMS Spy
Auditing records different attributes depending on the event category and type.
You can create separate queries for each event type or category to fetch event
category or type specific attributes.
The sample query below returns the audit records of resource access such as
creating a report, deleting a data source, or renaming a folder. For a complete list
of attributes recorded for each event type, see Audit Events in Oracle Business
Intelligence Publisher .
SELECT IAU_EVENTCATEGORY,
IAU_EVENTTYPE,
to_char("IAU_TSTZORIGINATING", 'DD-MON-YYYY HH24:MI:SSxFF') as
IAU_DATETIME,
IAU_INITIATOR,
IAU_EVENTSTATUS,
IAU_FAILURECODE,
IAU_MESSAGETEXT,
IAU_RESOURCE,
RESOURCETYPE,
RESOURCESUBTYPE,
NEWPATH,
NEWNAME
from BIPUBLISHER_V where IAU_EVENTCATEGORY = 'ResourceAccess'
5.
To test your data model, click View Data. Select a sample size, and run your data
model. Save the sample XML to your data model.
6.
Save your data model.
Creating the Report
Now you can use one of the BI Publisher's layout options to design the report layout
and visualize the auditing data.
To create a report using the BI Publisher layout editor
1.
On the global header, click New and then click Report.
2.
Select the data model you created in the previous procedure.
3.
Follow the instructions in the Create Report Wizard to create a report.
For complete instructions on using the layout editor, see Creating BI Publisher
Layout Templates in Report Designer's Guide for Oracle Business Intelligence
Publisher.
Viewing Performance Statistics in DMS Spy
Only users with administrator privileges can use the DMS Spy servlet to view the
performance statistics collected by the Report Event Monitor, User Event Monitor, and
Server Event Monitor.
To view performance statistics in DMS Spy
1.
Log in to http://server_address:enterprise_manager_port/dms/Spy as an
administrator.
2.
To view performance data, select option from Metrics Tables.
12-10
Chapter 12
Viewing Performance Statistics in the MBean Browser
Option
Description
BIPUBLISHER
Summary performance data of the server
BIPUBLISHER_Reports
Per-report performance data
BIPUBLISHER_Users
Per-user data
Viewing Performance Statistics in the MBean Browser
You can use the System MBean browser to view the performance statistics collected
by the Report Event Monitor, Server Event Monitor, and User Event Monitor.
To view performance statistics in the MBean browser
1.
In Oracle Fusion Middleware Control, click WebLogic Domain, and
select System MBean Browser.
2.
In the System MBean Browser, under the Application Defined MBeans, expand
the oracle.xdo folder to view the BI Publisher MBeans. Expand the list and select
the bean to view the details.
12-11
13
Adding Translations for the BI Publisher
Catalog and Reports
This chapter describes how to export and import translation files both for the catalog
and for individual report layouts.
It covers the following topics:
•
Introduction
•
Exporting and Importing a Catalog Translation File
•
Template Translation
•
Using the Localized Template Option
Introduction
BI Publisher supports two types of translation: Catalog Translation and Template (or
layout) Translation.
Catalog translation enables the extraction of translatable strings from all objects
contained in a selected catalog folder into a single translation file; this file can then be
translated and uploaded back to BI Publisher and assigned the appropriate language
code.
Catalog translation extracts not only translatable strings from the report layouts, but
also the user interface strings that are displayed to users, such as catalog object
descriptions, report parameter names, and data display names.
Users viewing the catalog see the item translations appropriate for the UI Language
they selected in their My Account preferences. Users see report translations
appropriate for the Report Locale that they selected in their My Account preferences.
Template translation enables the extraction of the translatable strings from a single
RTF-based template (including sub templates and style templates) or a single BI
Publisher layout template (.xpt file). Use this option when you only need the final report
documents translated. For example, your enterprise requires translated invoices to
send to German and Japanese customers.
This chapter describes the process of downloading and uploading translation files. For
more information on the concepts and processes of translating the files, see
Translating Reports and Catalog Objects in Report Designer's Guide for Oracle
Business Intelligence Publisher.
Limitations of Catalog Translation
If you have existing XLIFF file translations for specific reports and then you import a
catalog translation file for the folder in which the existing translations reside, the
existing XLIFF files are overwritten.
13-1
Chapter 13
Exporting and Importing a Catalog Translation File
Exporting and Importing a Catalog Translation File
This procedure describes the process of exporting an XLIFF file from the catalog,
importing the translated file back to the catalog, and testing the translation.
Importing and exporting XLIFF files can only be performed by an Administrator.
To import and export an XLIFF file:
1.
Select the folder in the catalog, click the Translation toolbar button, and then click
Export XLIFF.
2.
Save the XLIFF file to a local directory.
3.
Open the Translation file (catalog.xlf) and apply translations to the Boilerplate text,
as shown in the following figure.
See What Is an XLIFF? in Report Designer's Guide for Oracle Business
Intelligence Publisher for details on how to translate an XLIFF file.
4.
After the file is translated, upload the XLIFF file to the BI Publisher server: Click
the Translation toolbar button, then click Import XLIFF. Upload the translated
XLIFF to the server.
5.
To test the translation, select My Account from Signed In As in the global header.
6.
On the General tab of the My Account dialog, change the Report Locale and the
UI Language preferences to the appropriate language and click OK.
7.
View the objects in the translated folder.
Template Translation
RTF and BI Publisher (.xpt) templates can be translated from the Properties page.
Template translation includes:
13-2
Chapter 13
Template Translation
•
RTF templates
•
RTF sub templates
•
Style templates
•
BI Publisher templates (.xpt)
To access the Properties page, click the Properties link for the layout in the Report
Editor, as shown below.
From the Properties page you can generate an XLIFF file for a single template. Click
Extract Translation to generate the XLIFF file.
Generating the XLIFF File from the Layout Properties Page
Generate the XLIFF file for report layout templates, style templates, and sub
templates.
To generate the XLIFF file for report layout templates:
1.
Navigate to the report in the catalog and click Edit to open it for editing.
2.
From the thumbnail view of the report layouts, click the Properties link of the
layout (RTF or XPT) to open the Layout Properties page.
3.
In the Translations region, click Extract Translation.
BI Publisher extracts the translatable strings from the template and exports them
to an XLIFF (.xlf file).
4.
Save the XLIFF to a local directory.
To generate the XLIFF file for style templates and sub templates:
1.
Navigate to the style template or sub template in the catalog and click Edit to open
the Template Manager.
13-3
Chapter 13
Using the Localized Template Option
2.
In the Translations region, click Extract Translation.
BI Publisher extracts the translatable strings from the template and exports them
to an XLIFF (.xlf file).
3.
Save the XLIFF to a local directory.
Translating the XLIFF File
When you have downloaded the XLIFF file, it can be sent to a translation provider, or
using a text editor, you can enter the translation for each string.
See Structure of the XLIFF File inReport Designer's Guide for Oracle Business
Intelligence Publisher for instructions on how to edit the XLIFF file.
A "translatable string" is any text in the template that is intended for display in the
published report, such as table headers and field labels. Text supplied at runtime from
the data is not translatable, nor is any text that you supply in the Microsoft Word form
fields.
You can translate the template XLIFF file into as many languages as desired and then
associate these translations to the original template.
Uploading the Translated XLIFF File to BI Publisher
You can run the Template Manager to upload the translated XLIFF file to BI Publisher.
To upload a translated XLIFF file:
1.
Navigate to the report, sub template, or style template in the catalog and click Edit
to open it for editing.
For reports only:
From the thumbnail view of the report layouts, click the Properties link of the
layout to open the Template Manager.
2.
In the Translations region, click the Upload toolbar button.
3.
In the Upload Translation File dialog, locate the file in the local directory and select
the Locale for this translation.
4.
Click OK to upload the file and view it in the Translations table.
Using the Localized Template Option
If you need to design a different layout for the reports that you present for different
localizations, then you can create new RTF file that is designed and translated for the
locale and upload this file to the Template Manager.
Note:
The localized template option is not supported for XPT templates.
The process overview for using the localized template option is described in the
following sections:
13-4
Chapter 13
Using the Localized Template Option
•
Designing the Localized Template File
•
Uploading the Localized Template to BI Publisher
Designing the Localized Template File
Use the same tools that you used to create the base template file, translating the
strings and customizing the layout as desired for the locale.
Uploading the Localized Template to BI Publisher
Upload localized template files in rtf format.
To upload a localized template:
1.
Navigate to the report, subtemplate, or style template in the catalog and click Edit
to open it for editing.
For reports only:
From the thumbnail view of the report layouts, click the Properties link of the
layout to open the Template Manager.
2.
In the Templates region, click the Upload toolbar button.
3.
In the Upload Template File dialog, locate the file in the local directory, select rtf
as the Template Type and select the Locale for this template file.
4.
Click OK to upload the file and view it in the Templates table.
13-5
14
Moving Catalog Objects Between
Environments
This chapter describes how to move objects between test, production, and
development environments using the BI Publisher catalog utility.
It covers the following topics:
•
Overview
•
Preparing to Use the BI Publisher Catalog Utility
•
Exporting BI Publisher Reporting Objects
•
Importing BI Publisher Reporting Objects
•
Generating Translation Files and Checking for Translatability
Overview
The BI Publisher catalog utility enables administrators and report developers to export
the reporting object-related files from the catalog where all BI Publisher reports are
stored, and to import them to a different catalog.
Use this tool to manage BI Publisher reports using a third party tool as a source
control or to move a specific set of reports from a development environment to a
quality assurance or production environment. The catalog utility can also be used to
help manage translations of reporting objects.
Use the BI Publisher catalog utility to perform the following tasks:
•
Export BI Publisher reports from the catalog
•
Import BI Publisher reports into the catalog
•
Extract translatable strings and generate a translation file (XLIFF)
•
Generate a security.xml file that contains the reporting object-level permission
settings
When to Use the Catalog Utility
Use the catalog utility to move BI Publisher report artifacts from one environment to
another.
For example, use the catalog utility to move reports from a development environment
to a quality assurance environment. This process is illustrated in the figure below.
14-1
Chapter 14
Overview
Other Options for Moving Catalog Objects
To download or upload a small number of objects, the download feature of the BI
Publisher catalog enables you to bundle and download multicomponent objects (such
as reports) in an archive file. You can then use the upload feature to unarchive the
data to another location in the catalog.
See Downloading and Uploading Catalog Objects in User's Guide for Oracle Business
Intelligence Publisher.
Note:
Do not manually edit the BI Publisher files in the file system. BI Publisher uses
metadata files to maintain information about catalog objects. Manually editing
objects in the file system can result in the corruption of the metadata files. If
the metadata file becomes corrupt, then you can restore it by deleting the
corrupt file and restarting BI Publisher.
What Files Are Moved
Styles and skins are organized into folders that contain Cascading Style Sheets (CSS)
and images.
Object
Files
Report Example: Balance
+Letter.xdo
•
•
•
•
•
•
_report.xdo — The report definition file
xdo.cfg — The configuration file that contains the report
property settings
~metadata.meta — The metadata file that contains the
catalog path information. This file is used by the utility to
import objects back to their original locations.
security.xml file — Specifies the object level permissions
defined for the report
template files — All template files loaded to the report
definition. The file names include the language suffix, for
example: My_RTF_template_en_us.rtf,
My_BIP_layout_en_us.xpt
translation files — All translation files (.xlf), for example:
My_RTF_template_jp_jp.xlf
14-2
Chapter 14
Overview
Object
Files
Data Model Example:
myDataModel.xdm
•
•
•
Subtemplate Example:
mysubtempate.xsb
•
•
•
•
Style Template Example:
myStyleTemplate.xss
•
•
•
•
_datamodel.xdm — The report definition file
~metadata.meta — The metadata file that contains the
catalog path information. This file is used by the utility to
import objects back to their original locations.
security.xml file — Specifies the object level permissions
defined for the data model
_template_en_us.rtf — The subtemplate file with locale
designation
~metadata.meta — The metadata file that contains the
catalog path information. This file is used by the utility to
import objects back to their original locations.
security.xml file — Specifies the object level permissions
defined for the subtemplate
translation files — Any translations, when present; for
example: _template_jp_jp.rtf
_template_en_us.rtf — The style template file with locale
designation
~metadata.meta — The metadata file that contains the
catalog path information. This file is used by the utility to
import objects back to their original locations.
security.xml file — Specifies the object level permissions
defined for the style template
translation files — Any translations, when present; for
example: _template_jp_jp.rtf
Maintaining Identical Folder Names and Structure Across
Environments
A BI Publisher report references the following components using the physical path to
the component in the catalog: data models, subtemplates, and style templates.
When you move a report between environments the report maintains the physical
mappings to the referenced components. Therefore if you move a data model into a
different folder location under Shared Folders in the new environment, the report
cannot find the data model and the report does not run. In the case of style templates
or subtemplates, the report may run, but the referenced component is not applied.
For example, assume in your test environment Report A references Data Model B that
is located in Shared Folders/Test/Data Models. When you move this report and its
data model to the production environment you place Data Model B under the different
path Shared Folders/Data Models. When you run the report in the new environment it
still expects the data model to be located under Shared Folders/Test/Data Models.
The report cannot find the data model and does not run.
You can correct the mapping in the new environment by opening the report in the
report editor, selecting the data model in its new location, and saving the report.
To avoid manual steps, Oracle recommends that you maintain the same folder names
and structure in the environments across which you intend to move reports.
14-3
Chapter 14
Preparing to Use the BI Publisher Catalog Utility
Preparing to Use the BI Publisher Catalog Utility
The BI Publisher catalog utility is installed in the following location:
ORACLE_HOME/clients/bipublisher
Configuring the Environment
You must configure each environment in which you run the catalog utility.
To configure the environment for the catalog utility:
1.
Set the environment variables to the values in the following list:
•
path = ($HOME/BIPCatalogUtil/bin $path)
•
BIP_LIB_DIR = $HOME/BIPCatalogUtil/lib
•
BIP_CLIENT_CONFIG = $HOME/BIPCatalogUtil/config
•
JAVA_HOME = $HOME/java/jdk1.6.0_18
The following example shows setting the environment variables for C-shell:
%
%
%
%
2.
set path = ($HOME/BIPCatalogUtil/bin $path)
setenv BIP_LIB_DIR $HOME/BIPCatalogUtil/lib
setenv BIP_CLIENT_CONFIG $HOME/BIPCatalogUtil/config
setenv JAVA_HOME $HOME/java/jdk1.6.0_18
Edit xmlp-client-config.xml. This configuration file is located under the
BIPCatalogUtil/config directory.
Specify the BI Publisher instance URL ("bipurl") and the user name and password
of the BI Publisher instance from which you must export or to which you must
import.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<comment>BIP Server Information</comment>
<entry key="bipurl">http://sta00XXX.example.com:14001/xmlpserver/</entry>
<entry key="username">OPERATIONS</entry>
<entry key="password">welcome</entry>
</properties>
If you do not want to store this information in the configuration file, then at the time
of import/export you can also set the bipurl, username, and password as
parameters in the command line to overwrite values defined in xmlp-clientconfig.xml.
Exporting BI Publisher Reporting Objects
Use the export command to export either a single reporting object or a set of BI
Publisher reporting objects under a specified folder.
There are two export commands:
•
-export — Use this command to export a single report object.
•
-exportfolder — Use this command to export a folder and its contents.
14-4
Chapter 14
Exporting BI Publisher Reporting Objects
The table below describes the supported parameters for the -export and -exportfolder
commands.
Parameter
Used With
Sample
Description
catalogpath
-export exportfolder
/Samples/Financials/
Balance+Letter.xdo
The path to the object in the
catalog. If there are spaces in any
of the names, use the '+' sign as a
substitute.
target
-export
/tmp/Financials/
BalanceLetter
The destination directory in which
to place the extracted reporting
objects.
basedir
-exportfolder
/home/bipub/samples The base directory into which to
place subfolders of extracted
reporting objects. When present,
data models are saved to
{basedir}/datamodels; reports are
saved to {basedir}/reports; style
and subtemplates are saved to
{basedir}/templates.
extract
-export exportfolder
true/false
The default is false, which means
that the utility exports the reporting
object in a zip format that contains
all the related files such as '.xdo',
'.rtf', and '.cfg'. Use the default
option of exporting the reporting
object to a zip format to handle the
international characters. If you set
the value to 'true', then the utility
exports the reporting object-related
files under the specified target
folder.
subfolders
-exportfolder
true/false
When you specify a folder as the
"catalogpath" parameter, you can
use this "subfolders"' parameter to
control whether to download all
subfolder content. If you specify
true, then all reporting objects in all
subfolders are downloaded. If you
specify false, then subfolder
contents are not downloaded.
overwrite
-export exportfolder
true/false
Specify true to overwrite existing
objects in the target area.
Example Export Command Lines
Refer to the examples below on how to use the utility to export the reporting objects.
•
Exporting a Single Report in Archive Format
•
Exporting a Single Report with Files Extracted
•
Exporting a Set of Reports to a Specified Folder
14-5
Chapter 14
Importing BI Publisher Reporting Objects
Exporting a Single Report in Archive Format
The following example exports the reporting object in a zip format. The zip file contains
all the reporting object related files such as .xdo, .rtf, .cfg, and so on.
To extract a report in archived format use the ".xdoz" extension for the target. To
extract a data model, use the ".xdmz" extension.
$ BIPCatalogUtil.sh -export catalogpath=/Samples/Financials/Balance+Letter.xdo
target=/home/bipub/reports/BalanceLetter.xdoz extract=false
Exporting a Single Report with Files Extracted
The following example extracts the reporting object-related files to a directory named "/
home/bipub/reports/BalanceLetter". Existing files are overwritten.
$ BIPCatalogUtil.sh -export catalogpath=/Samples/Financials/Balance+Letter.xdo
target=/home/bipub/reports/BalanceLetter extract=true overwrite=true
Exporting a Set of Reports to a Specified Folder
The following example extracts all the reporting objects under the "/Samples" folder
and its subfolders in the catalog.
Data models are saved under {basedir}/datamodels. Reports are saved into {basedir}/
reports. Style and subtemplates are saved into {basedir}/templates.
$ BIPCatalogUtil.sh -exportfolder catalogpath=/Samples basedir=/home/bipub/samples
subfolders=true extract=true overwrite=true
Importing BI Publisher Reporting Objects
Use the import command to import either a single BI Publisher reporting object or a set
of BI Publisher reporting objects under a specified folder.
The table below describes the supported parameters for the import command.
Parameter
Sample
Description
catalogpath
/Samples/Financials/
Balance+Letter.xdo
Specify the catalog path to where you want to
import the reporting object only when you
want to override the default information. If you
do not specify this parameter, then the
reporting object is imported to the same
location where it was originally exported from.
source
/tmp/Financials/
BalanceLetter
The directory where the reporting object is
located. Use this parameter when you are
importing a single report.
basedir
/home/bipub/samples
The directory that contains multiple reports or
data models to be imported. Specify this
parameter when importing a set of reports or
data models.
overwrite
true/false
Specify 'true' to overwrite existing objects in
the target area.
14-6
Chapter 14
Generating Translation Files and Checking for Translatability
Typically, you import the reporting object to where it was originally exported from.
When you export the reporting object with the utility, it generates a metafile (.meta)
that contains the catalog path information. The utility uses this information to import
the reporting object to the original location. To import the objects into a different
location, you can override the original catalog path location by specifying the
catalogpath parameter.
Example Import Command Lines
Refer to the following examples on how to use the utility to import reports.
•
Importing a Report to an Original Location
•
Importing a Report to a New Location
•
Importing a Zipped Report
•
Importing a set of BI Publisher Reporting Objects Under a Specified Folder
Importing a Report to an Original Location
The following example imports a report to a catalog path saved in its metafile (.meta).
Existing reports are overwritten.
$ BIPCatalogUtil.sh -import source=/tmp/Financials/BalanceLetter overwrite=true
Importing a Report to a New Location
The following example imports a report into a new location in the catalog.
$ BIPCatalogUtil.sh -import source=/home/bipub/reports/BalanceLetter catalogpath=/
Production/Financials/Balance+Letter+Report.xdo
Importing a Zipped Report
The following example imports a zipped reporting object to an original location in the
catalog.
$ BIPCatalogUtil.sh -import source=/home/bipub/reports/BalanceLetter.xdoz
overwrite=true
Importing a set of BI Publisher Reporting Objects Under a Specified Folder
The following example imports all the reports under the base directory (basedir) into
the original locations in the catalog.
$ BIPCatalogUtil.sh -import basedir=/Users/bipub subfolders=true overwrite=true
Generating Translation Files and Checking for
Translatability
The catalog utility supports the -xliff command to generate a translatable XLIFF file for
a specific file.
The table below describes the supported parameters for generating XLIFF files.
14-7
Chapter 14
Generating Translation Files and Checking for Translatability
The source file can be the report definition (.xdo) file, an RTF template file (.rtf), or a BI
Publisher layout template file (.xpt). When the source is the .xdo file, the generated
XLIFF file includes all user-entered strings from the report definition interface, for
example: description, layout names, parameter names.
Parameter
Sample
Description
source
/Samples/Financials/
Balance+Letter.xdo
The path to the report or template file (RTF or
XPT) for which to generate the XLIFF file.
target
/home/bipub/reports/
Balance+Letter/Balance
+Letter.xlf
The location to save the generated .xlf
document.
basedir
/home/bipub/reports/
Balance+Letter/
The directory to place the generated .xlf files
into.
The following examples show how to generate translation files:
•
Generating a Translation File for a Report Definition File (.xdo)
•
Generating a Translation File for an RTF Template
Generating a Translation File for a Report Definition File (.xdo)
The following example generates an XLIFF file for a single report definition file.
$ BIPCatalogUtil.sh -xliff source=/home/bipub/reports/Balance+Letter/Balance
+Letter.xdo target=/home/bipub/reports/Balance+Letter/Balance+Letter.xlf
To save the XLIFF to a base directory:
$ BIPCatalogUtil.sh -xliff source=/home/bipub/reports/Balance/Balance+Letter.xdo
basedir=/home/bipub/reports/Balance+Letter/
Generating a Translation File for an RTF Template
The following example generates an XLIFF file for a single RTF template file.
$ BIPCatalogUtil.sh -xliff source=/home/bipub/reports/Balance+Letter/Balance+Letter
+Template.rtf target=/home/bipub/reports/Balance+Letter/Balance+Letter+Template.xlf
To save the XLIFF to a base directory:
$ BIPCatalogUtil.sh -xliff source=/home/bipub/reports/Balance/Balance+Letter
+Template.rtf basedir=/home/bipub/reports/Balance+Letter/
14-8
15
Customizing the BI Publisher User
Interface
The user interface in BI Publisher is generated by using scripts and is therefore highly
customizable. The look-and-feel is controlled by skins and styles. BI Publisher is
shipped with the Skyros (default style), and blafplus (browser look-and-feel plus),
styles.
The following sections provide information about how to customize the BI Publisher
user interface:
•
What are Skins and Styles?
•
About Style Customizations
•
Modifying the User Interface Styles for BI Publisher
•
Customizing the Style
What are Skins and Styles?
Styles and skins are organized into folders that contain Cascading Style Sheets (CSS)
and images.
Skins and styles are typically used to customize the look and feel of the BI Publisher
user interface by providing logos, color schemes, fonts, table borders, and other
elements. Skins and styles can also be used to control the position and justification of
various elements by including specialized style tags in the relevant style sheet file. For
more information, see About Style Customizations.
About Style Customizations
To customize the look-and-feel of BI Publisher, Oracle strongly recommends that you
use the custom style provided in the bicustom-template.ear file as your starting point.
This custom style is a copy of the Skyros style.
For more information, see Modifying the User Interface Styles for BI Publisher.
Most of the common Skyros styles and image files, including the style sheet
(master.css), are contained in the master directory. For more information about the
master directory and its structure, see About Style Customizations in System
Administrator's Guide for Oracle Business Intelligence Enterprise Edition.
Within the master.css style sheet, each element (or class) that is available for update
is documented in the comments.
Other style sheets are also contained within the Skyros style and skin folders. You are
not likely to need to update these files unless you are creating an advanced custom
skin that provides styles for each detail of the user interface.
15-1
Chapter 15
Modifying the User Interface Styles for BI Publisher
Note:
The Skyros style does not apply to Administration pages in BI Publisher.
Modifying the User Interface Styles for BI Publisher
To change the skin for BI Publisher, modify the xmlp-server-config.xml configuration
file located at CATALOG_DIRECTORY/Admin/Configuration/xmlp-server-config.xml .
To change the skin to blafplus, set the THEME property as follows:
<property name="THEME" value="blafplus"/>
To change the skin back to the default skin, Skyros, set the THEME property as
follows:
<property name="THEME" value="skyros"/>
Note:
The THEME property must be either "blafplus" or "skyros".
Customizing the Style
Enterprise Archive (EAR) files are archive (ZIP) files composed of a specific folder and
file structure. You can create an EAR file using any ZIP tool (for example, 7-zip) and
then rename the ZIP extension to EAR. Oracle provides the bicustom-template.ear file
as a starting point.
The bicustom-template.ear file contains a bicustom.war file. Web Archive (WAR) files
are also ZIP files composed of a specific folder and file structure. You must update the
bicustom.war file within the bicustom-template.ear file to include your custom skin files.
The bicustom.war file that is shipped with BI Publisher contains an example folder
structure to help you get started.
When creating styles and skins for BI Publisher, you must create CSS and image files,
and make them available to BI Publisher. Only the CSS defined in master.css and
images defined in the master folder can be customized for BI Publisher (bundled in the
bicustom.ear file.)
Customizing the Style for BI Publisher Standalone
Update selected configuration files to create a custom style for BI Publisher when BI
Publisher is not integrated with the Oracle BI Enterprise Edition.
To customize the style for BI Publisher standalone:
1.
Copy ORACLE_HOME\bifoundation\jee\bicustom-template.ear to
ORACLE_HOME\bifoundation\jee\bicustom.ear.
15-2
Chapter 15
Customizing the Style
Note:
The patch or upgrade process may overwrite the bicustom-template.ear file,
but it does not overwrite the bicustom.ear file.
2.
Extract the bicustom.war file from the bicustom.ear file to the machine where BI
Publisher is deployed.
3.
Extract the files from the bicustom.war file.
4.
Edit the master.css and images files in the unzipped directory to create the custom
style, and save the changes.
5.
Update the bicustom.war file with the changes.
6.
Update the bicustom.ear file with the new bicustom.war file.
7.
Deploy the new bicustom.ear file to the application server.
8.
Update the xmlp-server-config.xml file and save the changes.
The following example configurations assume that bicustom.ear file is deployed
with application name "custom" on the same application server where BI Publisher
is running:
<!-- required: this is the base skin to use for styles not defined inside custom
css -->
<property name="THEME" value="skyros"/>
<!-- required: this is the custom css http url -->
<property name="THEME_CUSTOM_MASTER_CSS_URL" value="/custom/res/s_Custom/master/
master.css"/>
<!-- required: this is the custom image http url prefix -->
<property name="THEME_CUSTOM_MASTER_IMAGE_URL_PREFIX" value="/custom/res/
s_Custom/master"/>
<!-- required: this is the file system path where custom images are located -->
<property name="THEME_CUSTOM_MASTER_IMAGE_PATH" value="/scratch/aime1/custom/res/
s_Custom/master"/>
Note that when a web page displays an image, the image is fetched through
HTTP. Therefore an image must be available through an HTTP URL no matter
where it is stored in the local directory. If you deploy bicustom.ear but place a
custom image in a unrelated local directory, the result is that the HTTP URL is
serving one image while the local directory is serving another image. To ensure
that the and HTTP URL and the local path are pointing to the same image file,
unpack bicustom.ear into the local directory (for example, path_A), make changes
to the css/images, and then install a "custom" application from the unpacked local
directory path_A.
9.
Restart BI Publisher.
For information on redeploying the bicustom.ear file, see Approach 1: Redeploying the
"bicustom.ear" File in System Administrator's Guide for Oracle Business Intelligence
Enterprise Edition.
15-3
Chapter 15
Customizing the Style
Customizing the Style for BI Publisher Integrated with the Oracle BI
Enterprise Edition
Update selected configuration files to create a custom style for BI Publisher integrated
with Oracle BI Enterprise Edition.
To customize the style for BI Publisher integrated with Oracle BI Enterprise Edition:
1.
Copy ORACLE_HOME\bifoundation\jee\bicustom-template.ear to
ORACLE_HOME\bifoundation\jee\bicustom.ear.
Note:
The patch or upgrade process may overwrite the bicustom-template.ear file,
but it does not overwrite the bicustom.ear file.
2.
Extract the bicustom.war file from the bicustom.ear file to the machine where BI
Publisher is deployed.
3.
Extract the files from the bicustom.war file.
4.
Edit the master.css and images files in the unzipped directory to create the custom
style, and save the changes.
5.
Update the bicustom.war file with the changes.
6.
Update the bicustom.ear file with the new bicustom.war file.
7.
Deploy the new bicustom.ear file to the application server.
8.
Update the xmlp-server-config.xml file and save the changes.
<!-- required: http url of OBIEE master css -->
<property name="THEME_MASTER_CSS_URL" value="/custom/s_skyros/master/
master.css"/>
<!-- required: this is the master css http url -->
<property name="THEME_IMAGE_URL_PREFIX" value="/custom/s_skyros/master"/>
<!-- required: this is the file system path where master images are located -->
<property name="THEME_MASTER_IMAGE_PATH" value="/scratch/aime1/bip/res/s_Custom/
master"/>
9.
Restart BI Publisher.
Note:
The custom configuration properties override the master configuration
properties; therefore the value of THEME_CUSTOM_MASTER_CSS_URL
takes precedence over the value of THEME_MASTER_CSS_URL. The same
rule applies for images.
15-4
Chapter 15
Customizing the Style
Fallback Mechanism for Custom Styles
When creating custom styles for BI Publisher (standalone and integrated Oracle BI
Enterprise), Oracle recommends that you copy only what you want to change in the
customization. Anything not copied "falls back" to the style specified in the base skin
for BI Publisher, which is the Skyros theme.
Custom Style Sheets
For custom style sheets (css), if THEME_CUSTOM_MASTER_CSS_URL is provided,
BI Publisher references those styles and ignores any others.
For custom style sheets (css), if THEME_CUSTOM_MASTER_CSS_URL is provided,
BI Publisher references those styles and ignores any others. If
THEME_MASTER_CSS_URL is provided, BI Publisher uses those styles. If neither
are provided, BI Publisher uses the styles defined in the base skin.
Images
BI Publisher constructs image URLs based on certain factors.
For images, if THEME_CUSTOM_MASTER_IMAGE_PATH is provided, and the
requested image exists in the directory, BI Publisher uses the value of
THEME_CUSTOM_MASTER_IMAGE_URL_PREFIX to construct the image URL.
If THEME_MASTER_IMAGE_PATH is provided and the requested image exists in the
directory, BI Publisher uses the value of THEME_MASTER_IMAGE_URL_PREFIX to
construct the image URL. If neither are provided, BI Publisher uses the images defined
in the base skin.
15-5
A
Scheduler Configuration Reference
This appendix describes how to configure the BI Publisher scheduler for each
supported database and how to configure ActiveMQ as the JMS provider.
It covers the following topics:
•
Introduction
•
Configuring BI Publisher for ActiveMQ
•
Manually Configuring the Quartz Scheduler
Introduction
The Oracle Business Intelligence Platform Installer configures the connection to the
scheduler and installs the scheduler schema to your selected scheduler database. The
WebLogic JMS queues are set up and the scheduler is up and running after
installation is complete and the servers have been started.
This information in this appendix is provided for reference for manually configuring the
scheduler and for setting up ActiveMQ as an alternative JMS provider.
For conceptual information about the scheduler, information for installing and
configuring additional managed servers, and a description of the scheduler diagnostics
page, see Configuring the Scheduler.
Configuring BI Publisher for ActiveMQ
The scheduler is configured by default to use WebLogic JMS. The scheduler also
supports ActiveMQ as an alternative JMS provider.
Use these guidelines with the ActiveMQ documentation to configure BI Publisher if you
choose to use ActiveMQ as the JMS provider.
Installing ActiveMQ
You can install Apache ActiveMQ version 5.2.0 or later in Windows, UNIX, or Linux.
Follow the installation steps documented in the ActiveMQ documentation.
Registering ActiveMQ as a JNDI Service
Update the activemq.xml configuration file to register ActiveMQ as a JNDI Service.
When you start ActiveMQ, the queues can be accessed using JNDI service.
The default URL to access this service is:
failover://tcp://localhost:61616
A-1
Appendix A
Manually Configuring the Quartz Scheduler
To change this configuration, update the activemq.xml configuration file found in
apache-activemq-x.x.x\conf for example: apache-activemq-5.2.0\conf.
Updating the BI Publisher Scheduler Configuration Page
Open the Scheduler Configuration page from the BI Publisher Administration page.
To update the BI Publisher Scheduler Configuration page:
1.
On the BI Publisher Administration page, under System Maintenance, click
Scheduler Configuration.
2.
Under the JMS Configuration region, select ActiveMQ.
3.
Enter the ActiveMQ JNDI URL. For example: failover://tcp://
localhost:61616.
4.
Enter the threads per processor (for example: 5).
5.
Enter the path to a shared temporary directory.
6.
Click Test JMS to test the connection.
7.
Click Apply to apply the changes to this page.
The ActiveMQ URL is dynamically applied. The queues and topics are automatically
created in ActiveMQ and are ready for scheduling. You can confirm the queues by
checking them in the Scheduler Diagnostics page. Alternatively, you can check the
status in the ActiveMQ Web console: http://localhost:8161/admin.
Manually Configuring the Quartz Scheduler
BI Publisher includes the Hyperion-branded DataDirect Connect for JDBC drivers to
setup a connection to install and use the scheduler tables in your database. These
drivers can be used as an alternative to the native JDBC drivers provided by your
database vendor.
When you choose a database for which a DataDirect driver is available, BI Publisher
automatically enters the database driver class information in the setup screen for you.
There is no additional setup required for the driver files.
If you choose to use a data direct driver not provided by the BI Platform Installer, then
you must download, install, and configure the driver manually.
Recommendations for Using DataDirect Connect or Native Database
Drivers
DataDirect Connect for JDBC drivers are provided for supported databases
Supported databases include:
•
IBM DB2 v8.1, v9.1
•
Microsoft SQL Server 2000, 2005
•
Sybase Adaptive Server Enterprise
•
Oracle 9i, Oracle 10g, Oracle 11g,
A-2
Appendix A
Manually Configuring the Quartz Scheduler
Note:
Some database options listed here and in the Scheduler page might not be
supported in this release. See System Requirements and Certification for the
most up-to-date information on supported hardware and software.
The table below displays the driver recommendations for the supported scheduler
databases.
Database
Native JDBC Driver
DataDirect JDBC Driver
Oracle 10g, Oracle 11g
Recommended
Supported
IBM DB2 v8.1, v9.1
Supported
Recommended
Microsoft SQL Server 2000,
2005
Supported
Recommended
Sybase Adaptive Server
Enterprise
Supported
Recommended
MySQL 4.1.10a-NT, 5.0
Supported
Not Supplied
Setting Up a User on Your Scheduler Database
To set up the connection to the scheduler database, you must ensure that you have
created a user on the selected database.
BI Publisher uses this user to connect to the database. Depending on the database
type, this user might require specific privileges. These are detailed in the databasespecific sections later in this appendix.
Connecting to Your Scheduler Database and Installing the Schema
Following are the general steps for setting up the Scheduler database. Also refer to
the subsequent section that is specific to your database.
To set up the Scheduler database:
1.
Log in to BI Publisher with Administrator credentials and select the Administration
tab.
2.
Under System Maintenance, click Scheduler Configuration.
3.
In the Scheduler Selection region, select Quartz.
Note:
The option "Enterprise Scheduler Services" is reserved for Oracle Fusion
Applications.
4.
Enter the following fields for the Database Connection:
A-3
Appendix A
Manually Configuring the Quartz Scheduler
•
Database Type — Select the database from the list. After you make a
selection, the Database Driver Class field automatically updates with the
recommended driver class.
•
Connection String — Enter the connection string for your selected database.
Sample strings are provided in the database-specific sections that follow.
•
Username and Password — Enter the scheduler user you set up for your
database. The user must have permissions to connect to the database and
create tables. Other permissions might be required depending on the
database type. See the appropriate database-specific section later in this
chapter.
•
Database Driver Class — When you select the database type this field is
automatically updated with the recommended driver. If you want to use
another driver, then specify it in this field.
Note:
Note: The Oracle database drivers and the DataDirect drivers are installed
with BI Publisher and no further setup is required. Note that for other
databases, even though the recommended native drivers are automatically
populated in this field, additional setup is required to make the drivers
available to BI Publisher.
5.
Click Test Connection to ensure that BI Publisher can connect to the database. If
the connection fails, ensure that you have entered the fields as shown and set up
your database appropriately.
6.
Click Install Schema to install the BI Publisher scheduler schema to your
database.
Connecting to Oracle Databases
When connecting to an Oracle database, ensure that the database user you enter has
"connect" or "create session" and "create table" privileges and that the user has been
assigned a quota (otherwise the quota is 0).
For example, the following sample creates the user "bipuser":
SQL>
2
3
4
5
6
CREATE USER bipuser
IDENTIFIED BY welcome
DEFAULT TABLESPACE USERS
TEMPORARY TABLESPACE TEMP
QUOTA 20G ON USERS
QUOTA 1M ON TEMP;
User created.
SQL> GRANT CREATE SESSION TO bipuser; -- or "GRANT CONNECT TO bipuser;"
Grant succeeded.
SQL> grant create table to bipuser;
Grant succeeded.
A-4
Appendix A
Manually Configuring the Quartz Scheduler
The table below describes the fields for the Oracle native driver to connect to the
Oracle Database.
Field
Description
Database Type:
Select Oracle 11g or Oracle 10g from the list.
Connection String:
Enter the following connection string parameters:
jdbc:oracle:thin:@<hostname>:<port>:<oracle SID> For
example: jdbc:oracle:thin:@mydatabaseserver.com:
1521:bipscheduler
Database Driver Class:
oracle.jdbc.driver.OracleDriver
Connecting to IBM DB2 Databases
When connecting to an IBM DB2 v8 or IBM DB2 v9 database, ensure that the user
that you enter to configure the scheduler has been set up with a 32 K page size
tablespace. If not, create the table and assign it to the user.
The user must also have "Connect to database" and "Create tables" privileges.
The table below describes the fields for the DataDirect driver to connect to an IBM
DB2 v8 or IBM DB2 v9 database.
Field
Entry
Database Type:
Select IBM DB2 v9 or IBM DB2 v8 from the list.
Connection String:
Enter the following connection string
parameters:jdbc:hyperion:db2://
<hostname>:<port>;DatabaseName=<DATABASENAME> For
example: jdbc:hyperion:db2:// mydatabaseserver.com:
1433;DatabaseName=bipscheduler
Database Driver Class:
hyperion.jdbc.db2.DB2Driver
Connecting to Microsoft SQL Server Databases
When connecting to a Microsoft SQL Server database, ensure that the Microsoft SQL
Server is set up with mixed mode authentication. Also ensure that the user that you
enter to configure the scheduler has the "db_owner" role.
The table below describes the fields for the DataDirect driver to connect to a Microsoft
SQL Server 2000 or 2005 database.
Field
Entry
Database Type:
Select Microsoft SQL Server 2000 or Microsoft SQL Server 2005
from the list.
Connection String:
Enter the following connection string parameters:
jdbc:hyperion:sqlserver://
<hostname>:<port>;DatabaseName=<DATABASENAME
>. For example: jdbc:hyperion:sqlserver://
mydatabaseserver.com:
1433;DatabaseName=bipscheduler.
Database Driver Class:
hyperion.jdbc.sqlserver.SQLServerDriver
A-5
Appendix A
Manually Configuring the Quartz Scheduler
Connecting to Sybase Adaptive Server Enterprise Databases
When connecting to an Sybase Adaptive Server Enterprise database, ensure that you
set the "ddl in tran" mode to true in the database. Consult the Sybase documentation
or contact your database administrator for instructions on how to enable this option.
The table below describes the fields for the DataDirect driver to connect to a Sybase
Adaptive Server Enterprise database.
Field
Entry
Database Type:
Select Sybase Adaptive Server Enterprise from the list.
Connection String:
Enter the following connection string parameters:
jdbc:hyperion:sybase://
<hostname>:<port>;DatabaseName=<DATABASENAME
>. For example: jdbc:hyperion:sybase://
mydatabaseserver.com:
4100;DatabaseName=bipscheduler.
Database Driver Class:
hyperion.jdbc.sybase.SybaseDriver
A-6
B
Integration Reference for Oracle BI
Enterprise Edition
This appendix describes configuration details for integrating BI Publisher with Oracle
BI Presentation Services and Oracle BI Server.
It covers the following topics:
•
About Integration
•
Configuring Integration with Oracle BI Presentation Services
•
Setting Up a JDBC Connection to the Oracle BI Server
About Integration
The information in this chapter is for reference to highlight the integration points
between BI Publisher and the Oracle BI Enterprise Edition.
You might need to reference this information in the following scenarios:
•
You are upgrading from a 10g release to the 11g release
•
You run a separate installation of BI Publisher and want to integrate it
•
You need to modify the installed configuration
The points of integration discussed in this chapter are:
•
Connecting to Oracle BI Server as a data source
•
Configuring integration with Oracle BI Presentation Services
Prerequisites
Oracle BI Publisher must be installed on the same server with the other components of
Oracle BI Enterprise Edition.
The security configuration must be either Oracle Fusion Middleware security or Oracle
BI Server security.
Configuring Integration with Oracle BI Presentation Services
When you install the Oracle BI Enterprise Edition, integration with BI Publisher is
automatically configured and "Server" and "Port" information remains uneditable.
Furthermore, the username and password fields are hidden, because both products
are configured to use Oracle Fusion Middleware security.
To configure integration with Oracle BI Presentation Services:
1.
From the Administration page, under Integration, click Oracle BI Presentation
Services.
B-1
Appendix B
Setting Up a JDBC Connection to the Oracle BI Server
2.
Enter the following information about your BI Presentation Services server:
•
Server Protocol — Select http or https
•
Server Version — Select v10
•
Server — Enter the server host name. For example: BIEEServer
•
Port — Enter the port for the server where the BI Presentation Services plugin is running. For example: 9502
•
Administrator Username and Password — These fields are hidden when
you use Oracle Fusion Middleware Security.
•
URL Suffix — Default value is: analytics/saw.dll
Note:
If your deployment is configured for SSO, then the suffix must be entered as
analytics-ws/saw.dll to enable the Web services between BI Publisher
and BI Presentation Services. For more information on configuring SSO for
Oracle BI Enterprise Edition, see Security Guide for Oracle Business
Intelligence Enterprise Edition.
•
Session time out in minutes
Setting Up a JDBC Connection to the Oracle BI Server
Make sure all prerequisites have been met before setting up a JDBC Connection o the
Oracle BI Server.
Note:
If you installed BI Publisher with the Oracle BI Enterprise Edition, then this
data source is automatically configured.
To add the Oracle BI Enterprise Edition server as a JDBC data source, follow the
guidelines in Setting Up a JDBC Connection to the Data Source with these specific
guidelines.
Note that if your Oracle BI Server is SSL-enabled, then you must copy the keystore to
the BI Publisher server and provide it in the connection string.
The entries for Database Driver Class and Connection String must be as follows:
Database Driver Class — oracle.bi.jdbc.AnaJdbcDriver
Connection String — The appropriate connection string depends on your specific
deployment. Clustered and SSL-enabled deployments require specific parameters to
construct the URL. For example, if the Oracle BI Server is SSL-enabled, then you
must copy the keystore to the BI Publisher server and provide it in the connection
string. For more information on SSL, see Security Guide for Oracle Business
Intelligence Enterprise Edition.
B-2
Appendix B
Setting Up a JDBC Connection to the Oracle BI Server
The URL for the connection string requires the following format:
<URL>:= <Prefix>: [//<Host>:<Port>/][<Property Name>=<Property Value>;]*
where
<Prefix> — The string jdbc:oraclebi
<Host> — The hostname of the analytics server. It can be an IP Address or hostname.
The default is localhost.
<Port> — The port number that the server is listening on. The default is 9703.
<Property Name>:= <Catalog>|<User>|<Password>|<SSL>|<SSLKeyStoreFileName> |
<SSLKeyStorePassword>|<TrustAnyServer>|<TrustStoreFileName >|<TrustStorePassword>|
<LogLevel>|<LogFilePath>|<PrimaryCCS>|<PrimaryCCSPort>| <SecondaryCCS>|
<SecondaryCCSPort>
Valid property values are:
<Catalog> — Any catalog name that is available on the server. If the catalog is not
specified, then it defaults to the default catalog specified by the server. If the catalog
name is not found in the server, then it still uses the default catalog and issues a
warning during connect.
<User> — Specifies the user name for the BI Server.
<Password> — Specifies the password for the BI Server for the user name.
<SSL> True|False — Default is False. Specifies if the JDBC driver uses SSL or not. If
true, then driver checks whether SSLKeyStoreFileName is readable; if not, it issues an
error message.
<SSLKeyStoreFileName> — Specifies the name of the file that store the SSL Keys.
This file must exist in the local file system and be readable by the driver.
<SSLKeyStorePassword> — Specifies the password to open the file pointed to by
SSLKeyStoreFileName.
<TrustAnyServer> - True | False — The default is False. If SSL is set to "True" the
property specifies whether to check the trust store for the server. If TrustAnyServer is
set to "False", the driver verifies that TrustStoreFileName is readable.
<TrustStoreFileName> — If TrustAnyServer is set to false, this property is required to
specify the trust store file name.
<TrustStorePassword> — If TrustAnyServer and TrustStoreFileName are specified,
this property specifies the password to open up the file specified by
TrustStoreFileName.
<LogLevel> — Specifies the log level. Valid values are
SEVERE | WARNING | INFO | CONFIG | FINE | FINER | FINEST
<LogFilePath> — Specifies the file path of the desired logging destination. Default is
%TEMP% on windows, $TMP on UNIX. Driver needs to have write permission on the
file. It creates a new entry marked as _0, _1 if the same file name exists.
<PrimaryCCS> — (For clustered configurations) specifies the primary CCS machine
name instead of using the "host" to connect. If this property is specified, the "host"
property value is ignored. The jdbc driver tries to connect to the CCS to obtain the
load-balanced machine. Default is localhost.
B-3
Appendix B
Setting Up a JDBC Connection to the Oracle BI Server
<PrimaryCCSPort> — Specifies the primary CCS port number running on the
PrimaryCCS machine. Default is 9706.
<SecondaryCCS> — Specifies the secondary CCS machine name instead of using
the "host" to connect. If this property is specified, then the jdbc driver tries to connect
to the CCS to obtain the load-balanced machine. Default is localhost.
<SecondaryCCSPort> — Specifies the secondary CCS port number running on the
secondary machine. Default is 9706.
Following is an example connection string for a clustered deployment with SSL
enabled:
jdbc:oraclebi://machine01.domain:9706/
PrimaryCCS=machine01;PrimaryCCSPort=9706;SecondaryCCS=machine02;SecondaryCCSPort=9706
;user=example;password=example;ssl=true;sslKeystorefilename=c:\example\OracleBI\sslc
\javahost.keystore;sslKeystorepassword=example;trustanyserver=true;
Use System User — you must select this box to use the BISystem User. When you
select this box, BI Publisher will use the BISystem Username and password to connect
to the BI Server. The Username and Password fields are no longer editable.
Username — leave blank
Password — leave blank
Use Proxy Authentication — (Required) select this box. Proxy authentication is
required.
B-4
C
Configuration File Reference
This appendix describes the BI Publisher runtime configuration file.
It covers the following topics:
•
BI Publisher Configuration Files
•
Setting Properties in the Runtime Configuration File
•
Structure of the Root Element
•
Properties and Property Elements
•
Font Definitions
•
Predefined Fonts
BI Publisher Configuration Files
This appendix contains reference information about the following BI Publisher
configuration file.
•
Runtime Configuration Properties File
The properties in the Runtime Configuration file are set through the Runtime
Configuration Properties, Currency Formats, and Font Mappings pages. See Setting
Runtime Properties.
Setting Properties in the Runtime Configuration File
The runtime properties and font mappings are set through the Runtime Configuration
Properties page and the Font Mappings page in the Administration interface.
If you do not use the Administration page to set the properties, then BI Publisher falls
back to the properties set in this file.
It is important to note that the Administration interface does not update this file. Any
settings in the Administration pages take precedence over the settings in the xdo.cfg
file.
File Name and Location
The configuration file is named xdo.cfg.
The file is located under the <BI Publisher Repository>/Admin/
Configuration.
Namespace
Namespace for configuration file.
http://xmlns.oracle.com/oxp/config/
C-1
Appendix C
Setting Properties in the Runtime Configuration File
Configuration File Example
Refer to the sample configuration file below.
<config version="1.0.0"
xmlns="http://xmlns.oracle.com/oxp/config/">
<!-- Properties -->
<properties>
<!-- System level properties -->
<property name="system-temp-dir">/tmp</property>
<!-- PDF compression -->
<property name="pdf-compression">true</property>
<!-- PDF Security -->
<property name="pdf-security">true</property>
<property name="pdf-open-password">user</property>
<property name="pdf-permissions-password">owner</property>
<property name="pdf-no-printing">true</property>
<property name="pdf-no-changing-the-document">true</property>
</properties>
<!-- Font setting -->
<fonts>
<!-- Font setting (for FO to PDF etc...) -->
<font family="Arial" style="normal" weight="normal">
<truetype path="/fonts/Arial.ttf" />
</font>
<font family="Default" style="normal" weight="normal">
<truetype path="/fonts/ALBANWTJ.ttf" />
</font>
<!--Font substitute setting (for PDFForm filling etc...) -->
<font-substitute name="MSGothic">
<truetype path="/fonts/msgothic.ttc" ttcno="0" />
</font-substitute>
</fonts>
</config>
Understanding the Element Specifications
The following is an example of an element specification:
<Element Name Attribute1="value"
Attribute2="value"
AttributeN="value"
<Subelement Name1/>[occurrence-spec]
<Subelement Name2>...</Subelement Name2>
<Subelement NameN>...</Subelement NameN>
</Element Name>
The [occurrence-spec] describes the cardinality of the element, and corresponds to the
following set of patterns:
•
[0..1] — Indicates the element is optional, and might occur only once.
•
[0..n] — Indicates the element is optional, and might occur multiple times.
C-2
Appendix C
Structure of the Root Element
Structure of the Root Element
The <config> element is the root element.
The element has the following structure:
<config version="cdata" xmlns="http://xmlns.oracle.com/oxp/config/">
<fonts> ... </fonts> [0..n]
<properties> ... </properties> [0..n]
</config>
Attributes of Root Element
The <config> element has the attributes described in the table below.
Attribute
Description
version
The version number of the configuration file format. Specify 1.0.0.
xmlns
The namespace for BI Publisher's configuration file. Must be http://
xmlns.oracle.com/oxp/config/
Description of Root Element
The root element of the configuration file.
The configuration file consists of two parts:
•
Properties (<properties> elements)
•
Font definitions (<fonts> elements)
The <fonts> and <properties> elements can appear multiple times. If conflicting
definitions are set up, the last occurrence prevails.
Properties and Property Elements
This section describes the <properties> element and the <property> element.
<properties> Element
The structure of the <properties> element is shown below.
<properties locales="cdata">
<property>...
</property> [0..n]
</properties>
Description of <properties> Element
The <properties> element defines a set of properties. You can specify the locales
attribute to define locale-specific properties. Following is an example:
<!-- Properties for all locales -->
<properties>
...Property definitions here...
C-3
Appendix C
Font Definitions
</properties>
<!--Korean specific properties-->
<properties locales="ko-KR">
...Korean-specific property definitions here...
</properties>
<property> Element
The structure of the <type1> element is shown below.
<property name="cdata">
...pcdata...
</property>
Attribute of <property> Element
The <property> element has a single attribute, name, which specifies the property
name.
Description of <property> Element
Property is a name-value pair. Specify the internal property name (key) to the name
attribute and the value to the element value.
The internal property names used in the configuration file are listed in the property
descriptions in Defining Runtime Configurations.
<properties>
<property name="system-temp-dir">d:\tmp</property>
<property name="system-cache-page-size">50</property>
<property name="pdf-replace-smart-quotes">false</property>
</properties>
Font Definitions
Font definitions include the specific elements.
Elements include:
•
<fonts>
•
<font>
•
<font-substitute>
•
<truetype>
•
<type1>
For the list of Truetype and Type1 fonts, see Predefined Fonts.
<fonts> Element
The structure of the <fonts> element is shown below.
<fonts locales="cdata">
<font> ... </font> [0..n]
C-4
Appendix C
Font Definitions
<font-substitute> ... </font-substitute> [0..n]
</fonts>
Attribute of <fonts> Element
The <fonts> element has a single optional attribute, locales, which specifies the
locales for this font definition.
Description of <fonts> Element
The <fonts> element defines a set of fonts. Specify the locales attribute to define
locale-specific fonts.
<!-- Font definitions for all locales -->
<fonts>
..Font definitions here...
</fonts>
<!-- Korean-specific font definitions -->
<fonts locales="ko-KR">
... Korean Font definitions here...
</fonts>
<font> Element
The structure of the <font> element is shown below.
<font family="cdata" style="normalitalic"
weight="normalbold">
<truetype>...</truetype>
or <type1> ... <type1>
</font>
Attributes of <font> Element
The <font> element has the attributes described in the table below.
Attribute
Description
family
Specify any family name for the font. If you specify "Default" for this
attribute, then you can define a default fallback font. The family
attribute is case-insensitive.
style
Specify "normal" or "italic" for the font style.
weight
Specify "normal" or "bold" for the font weight.
Description of <font> Element
Defines a BI Publisher font. This element is primarily used to define fonts for FO-toPDF processing (RTF to PDF). The PDF Form Processor (used for PDF templates)
does not refer to this element.
<!-- Define "Arial" font -->
<font family="Arial" style="normal" weight="normal">
<truetype path="/fonts/Arial.ttf"/>
</font>
C-5
Appendix C
Predefined Fonts
<font-substitute> Element
The structure of the <font-substitute> element is shown below.
<font-substitute name="cdata">
<truetype>...</truetype>
or <type1>...</type1>
</font-substitute>
Attributes of <font-substitute> Element
The <font-substitute> element has a single attribute, name, which specifies the name
of the font to be substituted.
Description of <font-substitute> Element
Defines a font substitution. This element is used to define fonts for the PDF Form
Processor.
<font-substitute name="MSGothic">
<truetype path="/fonts/msgothic.ttc" ttccno=0"/>
</font-substitute>
<type1> element
The structure of the <type1> element is shown below.
<type1 name="cdata"/>
Attribute of <type1> Element
The <type1> element has a single attribute, name, which specifies one of the Adobe
standard Latin1 fonts, such as "Courier".
Description of <type1> Element
The <type1> element defines an Adobe Type1 font.
<!--Define "Helvetica" font as "Serif" -->
<font family="serif" style="normal" weight="normal">
<type1 name="Helvetica"/>
</font>
Predefined Fonts
The following Type1 fonts are built-in to Adobe Acrobat and BI Publisher provides a
mapping for these fonts by default.
You can select any of these fonts as a target font with no additional setup required.
The Type1 fonts are listed in the table below.
C-6
Appendix C
Predefined Fonts
Number
Font Family
Style
Weight
Font Name
1
serif
normal
normal
Time-Roman
1
serif
normal
bold
Times-Bold
1
serif
italic
normal
Times-Italic
1
serif
italic
bold
Times-BoldItalic
2
sans-serif
normal
normal
Helvetica
2
sans-serif
normal
bold
Helvetica-Bold
2
sans-serif
italic
normal
Helvetica-Oblique
2
sans-serif
italic
bold
HelveticaBoldOblique
3
monospace
normal
normal
Courier
3
monospace
normal
bold
Courier-Bold
3
monospace
italic
normal
Courier-Oblique
3
monospace
italic
bold
CourierBoldOblique
4
Courier
normal
normal
Courier
4
Courier
normal
bold
Courier-Bold
4
Courier
italic
normal
Courier-Oblique
4
Courier
italic
bold
CourierBoldOblique
5
Helvetica
normal
normal
Helvetica
5
Helvetica
normal
bold
Helvetica-Bold
5
Helvetica
italic
normal
Helvetica-Oblique
5
Helvetica
italic
bold
HelveticaBoldOblique
6
Times
normal
normal
Times
6
Times
normal
bold
Times-Bold
6
Times
italic
normal
Times-Italic
6
Times
italic
bold
Times-BoldItalic
7
Symbol
normal
normal
Symbol
8
ZapfDingbats
normal
normal
ZapfDingbats
The TrueType fonts are listed in the table below. All TrueType fonts are subsetted and
embedded into PDF.
Number
Font Family Name
Style
Weight
Actual Font
Actual Font
Type
1
Albany WT
normal
normal
ALBANYWT.ttf
TrueType
(Latin1 only)
2
Albany WT J
normal
normal
ALBANWTJ.ttf
TrueType
(Japanese
flavor)
C-7
Appendix C
Predefined Fonts
Number
Font Family Name
Style
Weight
Actual Font
Actual Font
Type
3
Albany WT K
normal
normal
ALBANWTK.ttf
TrueType
(Korean
flavor)
4
Albany WT SC
normal
normal
ALBANWTS.ttf
TrueType
(Simplified
Chinese
flavor)
5
Albany WT TC
normal
normal
ALBANWTT.ttf
TrueType
(Traditional
Chinese
flavor)
6
Andale Duospace
WT
normal
normal
ADUO.ttf
TrueType
(Latin1 only,
Fixed width)
6
Andale Duospace
WT
bold
bold
ADUOB.ttf
TrueType
(Latin1 only,
Fixed width)
7
Andale Duospace
WT J
normal
normal
ADUOJ.ttf
TrueType
(Japanese
flavor, Fixed
width)
7
Andale Duospace
WT J
bold
bold
ADUOJB.ttf
TrueType
(Japanese
flavor, Fixed
width)
8
Andale Duospace
WT K
normal
normal
ADUOK.ttf
TrueType
(Korean
flavor, Fixed
width)
8
Andale Duospace
WT K
bold
bold
ADUOKB.ttf
TrueType
(Korean
flavor, Fixed
width)
9
Andale Duospace
WT SC
normal
normal
ADUOSC.ttf
TrueType
(Simplified
Chinese
flavor, Fixed
width)
9
Andale Duospace
WT SC
bold
bold
ADUOSCB.ttf
TrueType
(Simplified
Chinese
flavor, Fixed
width)
10
Andale Duospace
WT TC
normal
normal
ADUOTC.ttf
TrueType
(Traditional
Chinese
flavor, Fixed
width)
C-8
Appendix C
Predefined Fonts
Number
Font Family Name
Style
Weight
Actual Font
Actual Font
Type
10
Andale Duospace
WT TC
bold
bold
ADUOTCB.ttf
TrueType
(Traditional
Chinese
flavor, Fixed
width)
Included Barcode Fonts
BI Publisher includes a number of barcode fonts.
Barcode fonts are described in the table below.
Font File
Supported Algorithm
128R00.TTF
code128a, code128b, and code128c
B39R00.TTF
code39, code39mod43
UPCR00.TTF
upca, upce
For information on using barcode fonts in an RTF template, see Using the Barcode
Fonts Shipped with BI Publisher in Report Designer's Guide for Oracle Business
Intelligence Publisher.
C-9
D
Audit Reference for Oracle Business
Intelligence Publisher
This appendix provides reference information for auditing in Oracle Business
Intelligence Publisher.
This appendix contains these sections:
•
About Custom and Standard Audit Reports
•
Audit Events in Oracle Business Intelligence Publisher
About Custom and Standard Audit Reports
The Common Audit Framework in Oracle Fusion Middleware provides a set of
standard reports based on your audit records.
It also enables you to modify the standard reports and create your own custom audit
reports.
This appendix provides details about events that can be audited in Oracle Business
Intelligence Publisher. Use this information to understand the structure of each event
record to develop custom reports.
The following topics in Securing Applications with Oracle Platform Security Services
provide more information to help you write custom reports:
•
Attributes of Audit Reports in Oracle Business Intelligence Publisher.
•
Customizing Audit Reports.
The following topics provide additional information about how to configure auditing and
view standard reports:
•
Configuring auditing for Oracle Business Intelligence Publisher - See Enabling
Monitoring and Auditing.
•
List of events audited for Oracle Business Intelligence Publisher - See Viewing the
Audit Log.
Audit Events in Oracle Business Intelligence Publisher
Various attributes are used by audit events.
The table below lists the audit events and their attributes:
Event Category Event
Attributes used by Event
UserSession
UserLogin
EventCategory, EventType, TstzOrignating,
EventStatus, Initiator, MessageText
UserSession
UserLogout
EventCategory, EventType, TstzOrignating,
EventStatus, Initiator, MessageText
D-1
Appendix D
Audit Events in Oracle Business Intelligence Publisher
Event Category Event
Attributes used by Event
ReportAccess
ReportRequest
EventCategory, EventType, TstzOrignating,
EventStatus, Initiator, MessageText, FailureCode,
Resource, Format, Template
ReportAccess
ScheduledReportRe EventCategory, EventType, TstzOrignating,
quest
EventStatus, Initiator, MessageText, FailureCode,
Resource, Format, Template, JobID, OutputID
ReportAccess
ReportRepublish
ReportAccess
ReportDataDownloa EventCategory, EventType, TstzOrignating,
d
EventStatus, Initiator, MessageText, FailureCode,
Resource, OutputID
ReportAccess
ReportDownload
EventCategory, EventType, TstzOrignating,
EventStatus, Initiator, MessageText, FailureCode,
Resource, Format, Template, RepublishID
EventCategory, EventType, TstzOrignating,
EventStatus, Initiator, MessageText, FailureCode,
Resource, OutputID
ReportExecution ReportDataProcess
EventCategory, EventType, TstzOrignating,
EventStatus, Initiator, MessageText, FailureCode,
Resource, Format, Template, Locale, ProcessTime,
FreeMemory, TotalMemory, DataSize
ReportExecution ReportRendering
EventCategory, EventType, TstzOrignating,
EventStatus, Initiator, MessageText, FailureCode,
Resource, Format, Template, Locale, ProcessTime,
FreeMemory, TotalMemory, DataSize
ReportExecution ReportDelivery
EventCategory, EventType, TstzOrignating,
EventStatus, Initiator, MessageText, FailureCode,
Resource, JobID, ProcessTime, OutputName,
DeliveryMethod, DeliveryProperties, FreeMemory,
TotalMemory, DataSize
ReportJob
ReportJobSchedule
d
EventCategory, EventType, TstzOrignating,
EventStatus, Initiator, MessageText, FailureCode,
Resource, JobID, UserJobName, UserJobDescr,
JobGroup, RunType, Bursting, OutputInfo,
DeliveryInfo, StartDate, EndDate, Recurrence
ReportJob
ReportJobUpdated
EventCategory, EventType, TstzOrignating,
EventStatus, Initiator, MessageText, FailureCode,
Resource, JobID, UserJobName, UserJobDescr,
JobGroup, RunType, Bursting, OutputInfo,
DeliveryInfo, StartDate, EndDate, Recurrence
ReportJob
ReportJobCanceled
EventCategory, EventType, TstzOrignating,
EventStatus, Initiator, MessageText, FailureCode,
Resource, JobID
ReportJob
ReportJobDeleted
EventCategory, EventType, TstzOrignating,
EventStatus, Initiator, MessageText, FailureCode,
Resource, JobID
ReportJob
ReportJobPaused
EventCategory, EventType, TstzOrignating,
EventStatus, Initiator, MessageText, FailureCode,
Resource, JobID
ReportJob
ReportJobResumed EventCategory, EventType, TstzOrignating,
EventStatus, Initiator, MessageText, FailureCode,
Resource, JobID
D-2
Appendix D
Audit Events in Oracle Business Intelligence Publisher
Event Category Event
Attributes used by Event
ReportJob
ReportJobHistoryDel EventCategory, EventType, TstzOrignating,
eted
EventStatus, Initiator, MessageText, FailureCode,
Resource, JobID
ReportJob
ReportJobHistoryPur EventCategory, EventType, TstzOrignating,
ged
EventStatus, Initiator, MessageText, FailureCode,
Resource, JobID
ResourceAccess ResourceCreated
EventCategory, EventType, TstzOrignating,
EventStatus, Initiator, MessageText, FailureCode,
Resource, ResourceType, ResourceSubType
ResourceAccess ResourceUpdated
EventCategory, EventType, TstzOrignating,
EventStatus, Initiator, MessageText, FailureCode,
Resource, ResourceType, ResourceSubType
ResourceAccess ResourceDeleted
EventCategory, EventType, TstzOrignating,
EventStatus, Initiator, MessageText, FailureCode,
Resource, ResourceType, ResourceSubType
ResourceAccess ResourceCopied
EventCategory, EventType, TstzOrignating,
EventStatus, Initiator, MessageText, FailureCode,
Resource, NewPath, NewName
ResourceAccess ResourceRenamed
EventCategory, EventType, TstzOrignating,
EventStatus, Initiator, MessageText, FailureCode,
Resource, NewPath, NewName
D-3
E
Enabling Memory Guard Features
This section describes property settings available to safeguard your system against
memory failures caused by report requests that generate excessive data.
It includes the following sections:
•
What Are Memory Guard Features?
•
Key Features
•
Configuring Memory Guard and Data Model Properties
•
Configuring a Maximum Threads Constraint to Avoid Out of Memory Errors
What Are Memory Guard Features?
BI Publisher provides a set of features to protect against out-of-memory errors by
blocking report requests that generate excessive amounts of data or consume
excessive amount of memory.
These memory guard features consist of a set of properties. The properties enable you
to configure conditions and processing points at which data size and free memory
availability are inspected to determine whether the system continues to process a
report request or terminates processing.
Key Features
The section gives you information on the key features of memory guard and data
model properties.
The full set of properties is listed in Configuring Memory Guard and Data Model
Properties. The properties enable you to protect against out of memory errors and
enhance data processing by setting controls such as:
•
Maximum data size for reports
•
Maximum data size for scheduled reports
•
Minimum free memory size
•
SQL pruning for unused data set columns
•
Time out for SQL queries and also for reporting
The following section highlights some of the properties and provides detail on how the
system responds to the settings:
•
Restricting Maximum Data Sizes for Report Processing
•
Configuring Free Memory Threshold
•
Setting Data Engine Properties
E-1
Appendix E
Key Features
Restricting Maximum Data Sizes for Report Processing
By restricting the data size allowed for report processing you can prevent out of
memory errors when a query returns more data than the system can handle.
•
Specify a Maximum Data Size Allowed for Online Processing
•
Specify a Maximum Data Size Allowed for Offline (Scheduled Report) Processing
Specify a Maximum Data Size Allowed for Online Processing
Property: Maximum report data size for online reports.
This property enables you to specify a maximum data size allowed for online report
viewing. When you set a maximum data size, the following occurs when a user opens
a report for online viewing:
1.
A user submits a report to view online in the browser.
2.
The data engine generates the data for the report.
3.
Before document generation, the size of the data (in bytes) is inspected.
4.
If the data generated is larger than the maximum setting, the report processing is
ended. The user gets the following message:
The report you are trying to run exceeds the data limit set for this server. Either rerun with parameters that reduce the data or schedule this report. Contact your
Administrator if you have questions.
The user can then either set parameters (if available for the report) to limit the data
and resubmit online; or use the BI Publisher scheduler to submit the report.
The default value for this property is 300 MB.
Specify a Maximum Data Size Allowed for Offline (Scheduled Report) Processing
Property: Maximum report data size for offline (scheduled) reports.
This feature enables you to specify a maximum data size allowed for scheduled
reports. When you set a maximum data size, the following occurs when a scheduled
report job executes:
1.
The scheduler commences processing of a report job.
2.
The data engine generates the data for the report.
3.
If the data generated is larger than the maximum setting, the report processing is
ended. The scheduled report job fails with the following status message:
Report data size exceeds the maximum limit (<nnn> bytes). Stopped processing.
The user can then set parameters (if available for the report) to limit the data.
The default value for this property is 500 MB.
Configuring Free Memory Threshold
This set of properties helps you to protect against out of memory conditions by
establishing a minimum available free memory space.
E-2
Appendix E
Key Features
This set of properties enables your system to automatically protect free memory
availability and intelligently process reports with large data sets based on this
availability.
•
Specify A Minimum Free Memory Threshold for Report Processing
•
Specify Maximum Report Data Size Under the Free Memory Threshold
•
Set Minimum Time Span Between Garbage Collection Runs
•
Set Maximum Wait Time for Free Memory to Come Back Above the Threshold
Specify A Minimum Free Memory Threshold for Report Processing
Property: Free memory threshold
This setting enables you to specify a minimum value for free JVM space. This enables
you to control whether to run a report based on two factors: current usage and the size
of the report data. This feature requires the setting of several properties that work
together. You specify the threshold JVM space, the report maximum report size that
will be allowed when the JVM falls below the threshold, and the maximum wait time to
pause the report to wait for more JVM free space to become available.
When you set these properties, the following occurs when a user opens a report for
online viewing:
1.
A user submits a report to view online in the browser.
2.
The data engine generates the data for the report.
3.
JVM memory is inspected. If the available JVM memory is above the Free
memory threshold property value, the report processes as usual and there is no
system intervention.
If the available JVM memory is below the threshold value, the size of the report
data is inspected and compared to the property setting for Maximum report data
size under the free memory threshold. If the report data is below this threshold,
then the report continues processing.
If the report data size exceeds the threshold, then the report is paused to wait for
free memory to become available. The report will wait for the time specified in the
property Maximum Wait Time for Free Memory to Come Back Above
Threshold Value. If the free memory does not rise back above the minimum in the
wait period specified, the report request is rejected.
The default value for this property is 500 MB.
Specify Maximum Report Data Size Under the Free Memory Threshold
Property: Maximum report data size under the free memory threshold
Default value: (value of Free Memory Threshold)/10
Maximum single report data size allowed when free JVM memory is under the
specified threshold value set in Free memory threshold. For example (assuming the
default setting), if the data generated for a single report exceeds one-tenth of the value
set for Free memory threshold, then processing is terminated. Therefore if the Free
memory threshold is set to 100 MB and a single report data extract exceeds 10 MB,
then the report processing is terminated.
This property takes effect only when Free memory threshold is set to be a positive
value.
E-3
Appendix E
Key Features
Set Minimum Time Span Between Garbage Collection Runs
Minimum time span in seconds between any two subsequent garbage collection runs.
Set this value to avoid overrunning JVM garbage collection. The server enforces the
minimum of 120 seconds, which means the value will be reset to 120 seconds if it falls
below the minimum.
The default is 300 seconds.
Set Maximum Wait Time for Free Memory to Come Back Above the Threshold
The maximum time in seconds that a run-report request will wait for free JVM memory
to come back above the threshold value. This property value takes effect only when a
positive value for Free memory threshold is specified.
If the free memory becomes available within the time specified, the request will
proceed immediately to generate the document. If free memory is still below the
threshold value after the time specified, the request is rejected. For online requests,
the larger this property value, the longer the browser will wait for a request to run.
The default for this property is 30 seconds.
Setting Data Engine Properties
The data engine property settings provide additional points to protect your system
against out of memory errors.
These include:
•
Set Maximum Data Size That Can Be Generated by the Data Engine
•
Set Maximum Sample Data Size
•
Set Automatic Database Fetch Size
Set Maximum Data Size That Can Be Generated by the Data Engine
This property is used only when you generate XML data via data model editor. In a
normal report generation scenario, since template is chosen always, memory guard
side properties (maximum report data size for online/offline for each template type)
take precedence over this property.
Setting maximum data size sets an absolute limit to the data that can be generated
from the execution of a data model. This setting applies to both online report requests
and to requests submitted through the scheduler. When the size of the file generated
by the data engine exceeds the limit, the data engine terminates execution of the data
model and throws the exception:
"oracle.xdo.dataengine.diagnostic.XMLSizeLimitException: XML Output
(NNNNNNbytes) generated exceeds specified file size limit (NNNNNbytes)..!!!!!!!".
If the report request was submitted through the scheduler, the job will show as failed in
the Report Job History page. The exception error noted above displays when you rest
your cursor over the status. If the report request was submitted online, the user will get
the error "Unable to retrieve the data XML."
E-4
Appendix E
Configuring Memory Guard and Data Model Properties
Set Maximum Sample Data Size
A sample data set is required for all data models. The sample data is used during
template design. Sample data can be generated by the data model editor or uploaded
to the data model. Large sample data sets can impact the performance of the design
tools.
Set this property to limit the size of the sample data file that can be uploaded to the
data model.
Set Automatic Database Fetch Size
This setting calculates and sets database fetch size at run time depending on total
number of data set columns and total number of query columns. Setting this property
will override the server-level and data model-level database fetch size properties.
When set, this property takes effect for all data models and can significantly slow
processing time. This setting is recommended for implementations of BI Publisher that
frequently process complex queries of hundreds of columns, such as Oracle Fusion
Applications implementations. This setting is not recommended for most general
implementations of BI Publisher.
Configuring Memory Guard and Data Model Properties
Implement the memory guard features by setting the properties in the Properties tab
of the Administration > Runtime Configurationpage or by using the
runtimepropertiesconfig.sh command line utility.
The Memory Guard and Data Model property settings in the Properties tab of the
Administration > Runtime Configuration page are described in the following tables.
Memory Guard
Property description
Default Value
Maximum report data size for online reports
300MB
Maximum report data size for offline (scheduled)
reports
500MB
Free memory threshold
500MB
Maximum report data size under the free memory
threshold
free_memory_threshold/10
Maximum wait time for free memory to come back for 30 (seconds)
offline (scheduled) reports
Minimum time span between garbage collection runs
300 (seconds)
Maximum wait time for free memory to come back
above the threshold value
30 (seconds)
Timeout for online report
600 (seconds)
Maximum rows for CSV output
1000000
E-5
Appendix E
Configuring Memory Guard and Data Model Properties
Data Model
Property
Description
Maximum data size limit Default value: 500MB
for data generation
Maximum XML data size in that can be generated from the
execution of a data model. This setting applies to both online report
requests and to requests submitted through the scheduler. When the
size of the file generated by the data engine exceeds the value set
for this property, the data engine terminates execution of the data
model and throws an exception.
Validation rule: [1-9][0-9]*[KB|MB|GB]?
Examples:
•
123MB
•
128974848
•
2GB
•
2147483648
To turn this property off, enter 0 or a negative number.
Maximum sample data
size limit
Default value: 1MB
Enable Data Model
scalable mode
Default: True
Maximum file size of a sample data file that can be uploaded to the
data model editor.
Processing large data sets requires the use of large amounts of
RAM. To prevent running out of memory, activate scalable mode for
the data engine. In scalable mode, the data engine takes advantage
of disk space when it processes the data.
You can also set this property for specific data models. The data
model setting overrides the system setting here.
Enable Auto DB fetch
size mode
Default value: True
When set to True, BI Publisher calculates and sets database fetch
size at run time according to the total number of data set columns
and total number of query columns.
This setting avoids out of memory conditions, but can significantly
slow processing times.
When set to True, any other DB fetch size settings are ignored.
This setting is recommended for implementations of BI Publisher
that frequently process complex queries of hundreds of columns,
such as Oracle Fusion Applications implementations. This setting is
not recommended for most general implementations of BI Publisher.
This property overrides the data model- level database fetch size
properties.
When set, this property takes effect for all data models and can
significantly slow processing time.
E-6
Appendix E
Configuring Memory Guard and Data Model Properties
Property
Description
DB fetch size
Default value: 20 (rows)
The maximum database fetch size for a data model. This property
value takes effect only when Enable Auto DB fetch size mode is
set to False. When the fetch size is met, the rows are written to a
temp file and another fetch is executed; this process is repeated until
all the rows are returned to the temp file.
A smaller fetch size requires more round trips from BI Publisher to
the database and can impact overall processing time; however, the
smaller data chunks ensure against excessive memory usage.
This property can also be set at the data model level. The data
model setting overrides the server property.
SQL Query Timeout
Default: 600 seconds
Timeout for SQL query-based data models. If the SQL query is still
processing when the timeout value is met, the error "Failed to
retrieve data xml." is returned.
This property can also be set at the data model level. The data
model setting overrides the server property here.
Irrespective of the settings at the instance level or data model level,
the maximum SQL query timeout is 10 minutes for all BI Publisher
reports running online. This avoids stuck threads and server
outages.
Enable Data Model
diagnostic
Default value: False
Enable SQL Session
Trace
Default value: False
If you set this property to true, BI Publisher writes the data set
details, memory, and SQL execution time information to the log file.
Oracle recommends setting this property to true only for debugging
purposes. When set to true, processing time is increased.
If you set this property to true, for every SQL query that is executed,
BI Publisher writes a SQL session trace log to the database. A
database administrator can examine the log.
Oracle recommends that you turn this property on only in test and
development environments.
To enable this property, the user that you define for the database
connection must be granted the Alter Session privilege on the
database (Syntax: GRANT ALTER SESSION TO <USER NAME>).
See Setting Up a JDBC Connection to the Data Source.
Enable SQL Pruning
Default value: False
Applies to Oracle Database queries only that use Standard SQL. If
your query returns many columns but only a subset are used by your
report template, SQL pruning returns only those columns required by
the template. Setting this property enhances processing time and
reduces memory usage. Note that Enable SQL Pruning is also a
data model-level property that can be turned on or off for particular
data models to override this server-level setting.
SQL pruning is not applicable for PDF, Excel, and E-text template
types.
See Setting Data Model Properties in Data Modeling Guide for Oracle Business
Intelligence Publisher.
E-7
Appendix E
Configuring Memory Guard and Data Model Properties
Using runtimepropertiesconfig.sh Command Line Utility
This section describes how to use the runtimepropertiesconfig.sh command line utility
to configure the memory guard properties.
Command Line Utility Requirements
To run the runtimepropertiesconfig.sh command line utility, you must do the following:
•
Set the environment variable. For example, export JAVA_HOME=/home/jdk/
jdk1.8.0_40. By default, JAVA_HOME=$BI_HOME/jdk
•
Unzip the <BI_HOME>/modules/BIPConfigService.zip file and place the
runtimepropertiesconfig.sh utility in <BI_HOME>/modules/BIPConfigService/bin
directory.
cd <BI_HOME>/modules
unzip —d BIPConfigService BIPConfigService.zip
•
Change directory to the location of the runtimepropertiesconfig.sh command line
utility.
cd <BI_HOME>/modules/BIPConfigService/bin
•
Provide the path for BI_DOMAIN_HOME when the utility prompts.
For example: /user_projects/domains/bidomain/
Syntax
runtimepropertiesconfig.sh <Operation> <Options>
where
Operation: update, get, or help
Options for update operation : KEY1=VALUE1,KEY2=VALUE2
Options for get operation: KEY1,KEY2
Memory Guard Properties
Property
Description
server.ONLINE_REPORT_MAX_DATA_SIZE
Maximum report data size for online reports
Default value: 300MB
server.OFFLINE_REPORT_MAX_DATA_SIZE
Maximum report data size for offline
(scheduled) reports
Default value: 500MB
server.FREE_MEMORY_THRESHOLD
Free memory threshold
Default value: 500MB
server.MAX_DATA_SIZE_UNDER_FREE_MEMORY_T Maximum report data size under the free
memory threshold
HRESHOLD
Default value: free_memory_threshold/10
server.MINIMUM_SECOND_RUN_GARBAGE_COLLEC Minimum time span between garbage
collection runs
TION
Default value: 300 (seconds)
E-8
Appendix E
Configuring a Maximum Threads Constraint to Avoid Out of Memory Errors
Property
Description
server.WAIT_SECOND_FOR_FREE_MEMORY
Maximum wait time for free memory to come
back above the threshold value
Default value: 30 (seconds)
server.ONLINE_REPORT_TIMEOUT
Timeout for online reports.
Default value: 600 (seconds)
server.MAX_ROWS_FOR_CSV_OUTPUT
Maximum rows for CSV output
Default value: 1000000
server.XML_DATA_SIZE_LIMIT
Maximum data size limit for data generation
Default value: 500MB
server.MAX_SAMPLE_XML_DATA_SIZE_LIMIT
Maximum sample data size limit
Default value: 1MB
server.DB_FETCH_SIZE
DB fetch size
Default value: 20
server.SQL_QUERY_TIMEOUT
SQL Query Timeout
Default value: 600 (seconds)
Example E-1
Update Memory Guard Properties
The following command updates the values of server.ONLINE_REPORT_MAX_DATA_SIZE and
server.SQL_QUERY_TIMEOUT properties.
./runtimepropertiesconfig.sh update
server.ONLINE_REPORT_MAX_DATA_SIZE=223MB,server.SQL_QUERY_TIMEOUT=600
Example E-2
List Values of All Memory Guard Properties
The following command lists the values of all the memory guard properties.
./runtimepropertiesconfig.sh get
Example E-3
List Values of Specified Memory Guard Properties
The following command retrieves the values of the specified properties.
./runtimepropertiesconfig.sh get
server.ONLINE_REPORT_MAX_DATA_SIZE,server.SQL_QUERY_TIMEOUT
Example E-4
Get Help
The following command lists all the memory guard properties along with the default
value.
./runtimepropertiesconfig.sh help
Configuring a Maximum Threads Constraint to Avoid Out of
Memory Errors
During the processing of large BI Publisher reports Oracle WebLogic Server can use
multiple concurrent threads to generate the report.
If the threads are not constrained, out of memory errors can occur when Oracle
WebLogic Server allots too many threads to report generation. To avoid this error, you
E-9
Appendix E
Configuring a Maximum Threads Constraint to Avoid Out of Memory Errors
can create a Work Manager to enforce the maximum number of threads that Oracle
WebLogic Server can allot to BI Publisher report processing.
To configure a maximum threads constraint perform the following procedures:
1.
Creating the Maximum Threads Constraint in Oracle WebLogic Server
2.
Creating the Work Manager (XdoWorkManager)
3.
Redeploying the xmlpserver.ear File
Note:
This procedure describes redeploying the xmlpserver.ear file to activate the
new Work Manager. Alternatively, you can perform one of the following
instead of step 3:
•
Restart (stop & start) the bipublisher application
•
Restart the Oracle WebLogic Server instances (for example, bi_server1,
bi_server2)
Once this initial setup procedure is completed, changing the value of the maximum
threads count (for example from 10 to 20) takes effect immediately; no restart or
redeployment operations are required.
Creating the Maximum Threads Constraint in Oracle WebLogic Server
You create the maximum threads constraint component in the Oracle WebLogic
Console.
To create the maximum threads constraint component:
1.
Log in to Oracle WebLogic Console.
2.
In the Domain Structure pane, click Work Managers.
E-10
Appendix E
Configuring a Maximum Threads Constraint to Avoid Out of Memory Errors
3.
In the Change Center pane, click Lock & Edit.
4.
In the Work Managers, Request Classes and Constraints table, click New.
E-11
Appendix E
Configuring a Maximum Threads Constraint to Avoid Out of Memory Errors
5.
In the Create a New Work Manager Component dialog, select Maximum Threads
Constraint and click Next.
6.
Under Maximum Threads Constraint Properties, enter the following property
values:
•
Name — enter XdoMaxThreadsConstraint
•
Count — enter the maximum number of threads to allot for BI Publisher report
generation, for example, 10
E-12
Appendix E
Configuring a Maximum Threads Constraint to Avoid Out of Memory Errors
Click Next.
7.
Under Select deployment targets, select "bi_cluster" and then click Finish.
Creating the Work Manager (XdoWorkManager)
Now that you have created the Maximum Threads Constraint component and named it
"XdoMaxThreadsConstraint"; next create the work manager and associate it to the
XdoMaxThreadsConstraint component.
To create the work manager:
E-13
Appendix E
Configuring a Maximum Threads Constraint to Avoid Out of Memory Errors
1.
While still on the Summary of Work Managers page, click New again.
2.
In the Create a New Work Manager Component dialog, select Work Manager and
click Next
3.
Under Work Manager Properties enter the Name property as: XdoWorkManager.
E-14
Appendix E
Configuring a Maximum Threads Constraint to Avoid Out of Memory Errors
Click Next.
4.
Under Select deployment targets, select "bi_cluster" and then click Finish.
5.
Back on the Summary of Work Managers page, click your newly created
XdoWorkManager link.
E-15
Appendix E
Configuring a Maximum Threads Constraint to Avoid Out of Memory Errors
6.
On the Settings for XdoWorkManager page, on the Configuration tab, specify the
Maximum Threads Constraint as XdoMaxThreadsConstraint and click Save.
Redeploying the xmlpserver.ear File
You use the Upgrade Application Assistant to redeploy the xmlpserver.ear file.
To redeploy the xmlpserver.ear file:
1.
In the left pane of the Console, select Deployments.
E-16
Appendix E
Configuring a Maximum Threads Constraint to Avoid Out of Memory Errors
A table in the right pane displays all deployed applications and modules.
2.
In the table, select the bipublisher application.
3.
Click Update.
4.
In the Upgrade Application Assistant, click Next.
E-17
Appendix E
Configuring a Maximum Threads Constraint to Avoid Out of Memory Errors
5.
Click Finish.
6.
Click Activate Changes in the Change Center pane.
E-18
F
Updating the BI Publisher Context Root
This chapter describes how to change the default URL context root for BI Publisher.
•
Updating the BI Publisher URL Context Root
•
Example
Updating the BI Publisher URL Context Root
Change the default context to update the BI Publisher URL.
When you install BI Publisher with Oracle Business Intelligence, by default the context
for the BI Publisher URL is
http://<hostname>:<port>/xmlpserver
To change the default context like this:
http://<hostname>:<port>/<new context>/xmlpserver
perform the following general steps (detailed in the next section):
1.
Unzip the xmlpserver.ear file.
2.
Update the following xmlpserver configuration files:
•
META-INF/application.xml
•
WAR/WEB-INF/web.xml
•
WAR/WEB-INF/weblogic.xml
•
$DOMAIN_HOME/bidata/components/bipublisher/repository/Admin/
Configuration/xmlp-server-config.xml
3.
Repackage the xmlpserver.ear.
4.
Unzip the analytics.ear file.
5.
Update the following analytics file:
•
META-INF/application.xml
6.
Repackage the analytics.ear.
7.
Update the instanceconfig.xml.
8.
In WebLogic Server, update the bipublisher and analytics applications.
The following Example details the required updates in each file.
Example
This example details the required updates to change the BI Publisher context from
xmlpserver to /sales/xmlpserver.
F-1
Appendix F
Example
Perform these tasks:
•
Updating the xmlpserver META-INF/application.xml File
•
Updating the xmlpserver WAR/WEB-INF/web.xml File
•
Updating the xmlpserver WAR/WEB-INF/weblogic.xml File
•
Updating the xmlp-server-config.xml File
•
Updating the analytics META-INF/application.xml File
•
Updating the instanceconfig.xml File
•
Updating the bipublisher and analytics Applications in WebLogic Server
Updating the xmlpserver META-INF/application.xml File
Update the context-root of the META-INF/application.xml file.
1.
Unzip the xmlpserver.ear file.
2.
Navigate to META-INF/application.xml under the xmlpserver WAR.
3.
Update the context-root to match you new context. In this example the context root
is updated to /sales/xmlpserver:
<web>
<web-uri>xmlpserver.war</web-uri>
<context-root>/sales/xmlpserver</context-root>
</web>
Updating the xmlpserver WAR/WEB-INF/web.xml File
Under the xmplserver WAR/WEB-INF folder, update the web.xml file.
1.
Navigate to the WAR/WEB-INF/web.xml file.
2.
Update the following parameter values in the file:
<init-param>
<!-- This is the root webdir for the xmlpserver application. Modify this if
xmlpserver.ear is not deployed to its standard location. -->
<param-name>xmlp-online-web-dir</param-name>
<param-value>/sales/xmlpserver</param-value>
</init-param>
<init-param>
<!-- Path to the ServiceGateway SOAP end point. Most likely this will be the
path for services deployed with Axis. -->
<param-name>service-endpoint</param-name>
<param-value>/sales/xmlpserver/services/ServiceGateway</param-value>
</init-param>
<init-param> <!-- Path to report service web directory. -->
<param-name>web-dir</param-name>
<param-value>/sales/xmlpserver/report_service</param-value>
</init-param>
Updating the xmlpserver WAR/WEB-INF/weblogic.xml File
Under the xmplserver WAR/WEB-INF folder, update the weblogic.xml file.
F-2
Appendix F
Example
1.
Navigate to the WAR/WEB-INF/weblogic.xml file.
2.
Update the cookie-path and context-root in the file:
<wls:session-descriptor>
<wls:cookie-path>/sales/xmlpserver</wls:cookie-path>
</wls:session-descriptor>
<wls:context-root>sales/xmlpserver</wls:context-root>
Updating the xmlp-server-config.xml File
Update an element in the xmlp-server-config.xml file.
1.
Navigate to:
Oracle_Home/user_projects/domains/bi/bidata/components/bipublisher/repository/
Admin/Configuration/xmlp-server-config.xml
2.
Update the following element in the file:
<property name="SAW_URL_SUFFIX" value="sales/analytics/saw.dll"/>
Updating the analytics META-INF/application.xml File
Update the elements in the file to match your context-root.
1.
Unzip the analytics.ear file.
2.
Navigate to the META-INF/application.xml file.
3.
Update the following elements to match your context-root:
<display-name>analytics</display-name>
<module>
<web>
<web-uri>analytics.war</web-uri>
<context-root>sales/analytics</context-root>
</web>
</module>
<module>
<web>
<web-uri>analytics-ws.war</web-uri>
<context-root>sales/analytics-ws</context-root>
</web>
</module>
<module>
<web>
<web-uri>analytics.war</web-uri>
<context-root>sales/analytics-bi-adf</context-root>
</web>
</module>
Updating the instanceconfig.xml File
Update the instanceconfig.xml file.
1.
Navigate to the instanceconfig.xml located at
[ORACLE_INSTANCE]\config\OracleBIPresentationServicesComponent
\coreapplication_obips1\instanceconfig.xml
F-3
Appendix F
Example
2.
Update the <ServerBasedURL> and <WebURL> elements under
<AdvancedReporting> in the file:
<AdvancedReporting>
<ServerBaseURL>/sales/xmlpserver</ServerBaseURL>
<WebURL>/sales/xmlpserver</WebURL>
</AdvancedReporting>
Updating the bipublisher and analytics Applications in WebLogic
Server
Update the bipublisher and analytics applications in the Oracle WebLogic Server
Administration Console.
1.
Repackage the xmplserver.ear file.
2.
Repackage the analytics.ear file.
3.
Open your Oracle WebLogic Server Administration Console.
4.
In the Change Center of the Administration Console, click Lock & Edit.
5.
In the left pane of the Console, select Deployments. A table in the right pane
displays all deployed Enterprise Applications and Application Modules.
6.
In the table, select the bipublisher application.
7.
Click Update.
8.
Click Finish (do not change the source path).
9.
Repeat Step 6 through Step 8 for the analytics application.
10. In the Change Center of the Administration Console, click Activate Changes
and then click Release Configuration.
F-4
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement