Oracle Warehouse Builder Installation and Administration Guide, 11g Release 2 (11.2)

11g Release 2 (11.2)

E17130-05

Contents

List of Examples

List of Figures

List of Tables

Title and Copyright Information

Preface

- Audience

- Documentation Accessibility

- Related Documents

- Conventions

Part I Installing and Configuring Oracle Warehouse Builder

1 Overview of Installation and Configuration Architecture

- Choosing an Appropriate Installation Configuration

- Architecture and Components of Oracle Warehouse Builder

- Single Computer Topology

- Separate Client and Database Server Topology

- Multiple Database Topology

- Separate Client, Control Center Service, and Database Server Topology

- Control Center Agent Topology

- About the Check for Updates Wizard for Oracle Warehouse Builder

2 Installing Oracle Warehouse Builder on the Server

- Installing Oracle Warehouse Builder on Oracle Database 11g Release 2

- Working with Oracle Warehouse Builder Standalone Install Package

- Installing Oracle Warehouse Builder Through Oracle Universal Installer

- Installing Oracle Warehouse Builder in Oracle RAC Environments

- Installing Oracle Warehouse Builder on Each Node of a Cluster

- Checklist: Before Using the Universal Installer in an Oracle RAC Environment

- For Windows Users Installing in an Oracle RAC Environment

- For UNIX Users Installing in an Oracle RAC Environment

- Ensuring the Availability of Service Names for Oracle RAC Nodes

- Performing a Silent Install and Using Response Values

- After the Installation is Complete

3 Configuring Oracle Warehouse Builder for Windows

- Configuring Oracle Warehouse Builder on Windows Installed as Part of Oracle Database 11g Release 2

- Configuring Oracle Warehouse Builder on Windows Installed as a Standalone Instance

- About Configuring Oracle Warehouse Builder Installed as a Standalone Instance

- Cleaning an Oracle Warehouse Builder Repository

- Creating an OWBSYS Schema with Repository Objects

- Configuring the Control Center Service

- Unlocking the OWBSYS and OWBSYS_AUDIT Accounts

- Configuring Oracle Workflow to Support Oracle Warehouse Builder Process Flows

- Setting Oracle Warehouse Builder Home for Remote Installations

- Creating the First Workspace in the Repository on Windows

4 Configuring Oracle Warehouse Builder for Linux

- Configuring Oracle Warehouse Builder on Linux Installed as Part of Oracle Database 11g Release 2

- Configuring Oracle Warehouse Builder on Linux Installed as a Standalone Instance

- About Configuring Oracle Warehouse Builder Installed as a Standalone Instance

- Cleaning an Oracle Warehouse Builder Repository

- Creating an OWBSYS Schema with Repository Objects

- Configuring the Control Center Service

- Unlocking the OWBSYS and OWBSYS_AUDIT Accounts

- Configuring Oracle Workflow to Support Oracle Warehouse Builder Process Flows

- Setting the Oracle Warehouse Builder Home for Remote Installations

- Creating the First Workspace in the Repository on Linux

5 Uninstalling Oracle Warehouse Builder

- About Uninstalling Oracle Warehouse Builder

- Deleting the Workspace Users

- Deleting the Workspace

- Deleting the Schema Objects

- Deleting a Repository from an Oracle Database

- Uninstalling the Oracle Warehouse Builder Software

6 Moving to Oracle Warehouse Builder 11.2 from Earlier Releases

- Understanding MDL Migration and Repository Upgrades

- Choosing Between MDL Migration and Repository Upgrade

- MDL Migration Paths

- Repository Upgrade Paths from Oracle Warehouse Builder 10.1 or 9.n to Release 11.2

- Choosing a Repository Upgrade Scenario

- In-Place Upgrade of Oracle Warehouse Builder 10g Release 2 or 11g Release 1 Repository to Oracle Warehouse Builder 11g Release 2

- Preparing for In-Place Repository Upgrade

- Performing the In-Place Repository Upgrade

- Upgrading a Repository to Release 11.2 through MDL Files

- Exporting an Oracle Warehouse Builder Repository to a File

- Importing a Repository Export MDL File to Oracle Warehouse Builder Release 11.2

- Deploying Any Process Flow Package With Repository Upgrade to Release 11.2

- Migrating the Repository to a Different Oracle Database Instance

- Upgrading Locations to Oracle Warehouse Builder Release 11.2

- Upgrading Locations to Oracle Warehouse Builder Release 11.2 Using the Repository Browser

- Changes to Repository Objects When Moving to Oracle Warehouse Builder 11g Release 2

7 Configuring Repository Browser, Control Center Agent, and Other Components

- Configuring the Repository Browser Environment

- Changing the Session Timeout

- Configuring Control Center Agent for Oracle Application Server

- Modifying the OC4J Startup Script

- Configuring Control Center Agent Server-side Logging

- Configuring the Audit Data Source

- Setting Control Center Agent Security Roles

- Creating JMS Queues

- Setting the PATH Environment Variable

- Deploying the Control Center Agent to OC4J

- Configuring the Control Center Agent Web Service (jrt-web.war)

- Enabling Control Center Agent Audit Table Logging

- Configuring OWBSYS Audit Connection Pool

- Configuring an Audit Table Data Source

- Installing JDBC Drivers for OC4J

- Overview of Control Center Agent Files

- ODL Job Log Files

- Control Center Agent Run-Time Log File

- JobID File

- Control Center Agent Settings

- JRTAdministratorMBean

- Installing Code Templates for Use from Control Center Agent

- Integrating with E-Business Suite

- Installing Third-Party Name and Address Data

- Integrating with Oracle Workflow

Part II Administering Oracle Warehouse Builder

8 Managing Configurations

- About Configuration Management

- Creating Configurations Templates

- Editing Configuration Templates

- Activating Configurations

- Configuring Objects

9 Managing the Control Center and Repository

- Overview of Oracle Warehouse Builder Control Center and Repository Management

- Starting and Stopping the Control Center Service

- Displaying and Managing Control Center Configuration

- Managing Control Center Deployment and Execution Jobs

- Oracle Warehouse Builder Repository and Location Administration Utilities

- Oracle Warehouse Builder Administrative Utilities

- abort_exec_request

- abort_unit_request

- deactivate_all

- deactivate_deployment

- deactivate_execution

- delete_warehouse_object

- display_platform_property

- expedite_exec_request

- grant_error_table_privileges

- grant_upgrade_privileges

- list_requests

- print_exec_details

- print_running_exec_details

- purge_audit_template

- reset_repository

- rtrepos_report

- service_doctor

- set_ccs_home

- set_platform_property

- set_platform_property_from_file

- set_repository_password

- show_service

- sqlplus_exec_background_template

- sqlplus_exec_template

- start_service

- stop_service

- UpdateControlCenter

- UpdateLocation

- Overview of Oracle Warehouse Builder Repository Browser

- Starting the Repository Browser

- How to Start the Repository Browser Listener

- How to Stop the Repository Browser Listener

10 Managing the Control Center Agent

- Starting and Stopping the Control Center Agent

- About the cca_admin Utility

- Starting the cca_admin Utility

- cca_admin Commands

- cleanUpJobLogFilesForGivenTimeInterval

- cleanUpNLeastRecentJobLogFiles

- connect

- disconnect

- exit

- getCacheJobStatusSize

- getCacheLogNo

- getKmPermissionsFile

- getLogRoot

- getMaxAbortTimeout

- getMaxRuntimeFileSizeMB

- getMaxRuntimeLogSizeMB

- getRuntimeLogEncoding

- getRuntimeLogFileLocation

- getRuntimeLogLevel

- help

- isKmSecurityNeeded

- isLogToAuditTable

- isLogToOdl

- isShowRuntimeLoggerLogHostAddr

- isShowRuntimeLoggerLogHostId

- isShowRuntimeLoggerLogMsgClassPath

- isShowRuntimeLoggerLogMsgLogLevel

- isShowRuntimeLoggerLogUserId

- readSettings

- reset

- setCacheJobStatusSize

- setCacheLogNo

- setKmPermissionsFile

- setKmSecurityNeeded

- setLogRoot

- setLogToAuditTable

- setLogToOdl

- setMaxAbortTimeout

- setMaxRuntimeFileSizeMB

- setMaxRuntimeLogSizeMB

- setRuntimeLogEncoding

- setRuntimeLogLevel

- setShowRuntimeLoggerLogHostAddr

- setShowRuntimeLoggerLogHostId

- setShowRuntimeLoggerLogMsgClassPath

- setShowRuntimeLoggerLogMsgLogLevel

- setShowRuntimeLoggerLogUserId

- settingsToString

- showAllJobLogFiles

11 Using Snapshots to Manage Metadata

- About Snapshots and Metadata Loader

- Using Snapshots

- Creating Snapshots

- Adding Components to a Snapshot

- Managing Snapshots

- Managing Snapshot Access Privileges

- Comparing Snapshots

- Converting a Full Snapshot to a Signature Snapshot

- Restoring Workspace Objects From Snapshots

- Exporting and Importing Snapshots

- Deleting Snapshots

- Snapshot Performance

12 Importing, Exporting, and Upgrading Metadata

- Exporting Metadata from the Design Center

- Importing Metadata Using the Design Center

- Importing Objects

- Combining Import Modes and Matching Criteria

- Import Different Base Languages

- Different Base Languages in the Import File and Target Repository

- Importing Supported Languages

- Import Validation Rules

- Upgrading Metadata from Earlier Releases

- Changes to Workspace Objects When Upgrading from Oracle Warehouse Builder 9.2

- Changes to Workspace Objects When Upgrading from Oracle Warehouse Builder 10.1, 10.2 or 11.1

- Checking for Warnings and Error Messages

- Design Center Metadata Management Dialog Boxes

- Metadata Export Dialog Box

- Export Advanced Options Dialog Box

- Languages

- Administration

- Metadata Import Dialog Box

- Import Advanced Options Dialog Box

- Languages

- Administration

- Name Conflicts

- File Summary Dialog Box

- Metadata Upgrade Dialog Box

- Metadata Progress Dialog Box

- Metadata Loader Utilities

- Metadata Export Utility

- Metadata Import Utility

- Multiple Session Concurrency and MDL

- Metadata Loader Log File

- About Metadata Loader Results

- Managing Versions and History with the Metadata Loader

- Accessing the Metadata Loader

- About Metadata Loader Control Files

13 Managing Security

- About Metadata Security

- About the Security Service

- Evaluating Metadata Security Strategies

- Minimal Metadata Security Strategy (Default)

- Multiuser Security Strategy

- Full Metadata Security Strategy

- Registering Database Users

- Registering Existing Database Users

- Creating New Oracle Database Users

- Changing Database Default Roles

- Editing User Profiles

- Roles

- Default Object Privilege

- Object Privileges

- System Privileges

- Support for a Multiple-user Environment

- Read/Write Mode

- Read-Only Mode

- Defining Security Roles

- Everyone Role

- Administrator Role

- Editing Role Profiles

- Users

- Applying Security Properties on Specific Metadata Objects

- Security Tab

- Example: Using Security Properties to Freeze a Project Design

- Security Enforcement

- Managing Passwords in Oracle Warehouse Builder

- Credential Memory on Logon Panel

- Changing Passwords that Access Oracle Warehouse Builder

- Encrypting Passwords to Oracle Warehouse Builder Locations

A Troubleshooting the Installation and Setup

- General Steps for Troubleshooting Oracle Warehouse Builder

- Inspecting Log Files in Oracle Warehouse Builder

- Error Messages Related to Installation

- Troubleshooting Other Installation Problems

- Checking the Java Virtual Machine (JVM)

- Using Oracle Warehouse Builder Client Logging to Control Logging and Trace Problems

- Checking the System Path of Oracle Warehouse Builder

- Configuring Oracle Warehouse Builder for Oracle RAC

Index

List of Examples

- 10-1 Using cleanUpJobLogFilesForGivenTimeInterval Command

- 10-2 Using cleanUpNLeastRecentJobLogFiles command

- 10-3 Using connect Command

- 10-4 Using disconnect Command

- 10-5 Using exit Command

- 10-6 Using getCacheJobStatusSize Command

- 10-7 Using getCacheLogNo Command

- 10-8 Using getKmPermissionsFile Command

- 10-9 Using getLogRoot Command

- 10-10 Using getMaxAbortTimeout Command

- 10-11 Using getMaxRuntimeFileSizeMB Command

- 10-12 Using getMaxRuntimeLogSizeMB Command

- 10-13 Using getRuntimeLogEncoding Command

- 10-14 Using getRuntimeLogFileLocation Command

- 10-15 Using getRuntimeLogLevel Command

- 10-16 Using help Command

- 10-17 Using isKmSecurityNeeded Command

- 10-18 Using isLogToAuditTable Command

- 10-19 Using isLogToOdl Command

- 10-20 Using isShowRuntimeLoggerLogHostAddr Command

- 10-21 Using isShowRuntimeLoggerLogHostId Command

- 10-22 Using isShowRuntimeLoggerLogMsgClassPath Command

- 10-23 Using isShowRuntimeLoggerLogMsgLogLevel Command

- 10-24 Using isShowRuntimeLoggerLogUserId Command

- 10-25 Using readSettings Command

- 10-26 Using reset Command

- 10-27 Using setCacheJobStatusSize Command

- 10-28 Using setCacheLogNo Command

- 10-29 Using setKmPermissionsFile Command

- 10-30 Using setKmSecurityNeeded Command

- 10-31 Using setLogRoot Command

- 10-32 Using setLogToAuditTable Command

- 10-33 Using setLogToOdl Command

- 10-34 Using setMaxAbortTimeout command

- 10-35 Using setMaxRuntimeFileSizeMB Command

- 10-36 Using setMaxRuntimeLogSizeMB Command

- 10-37 Using setRuntimeLogEncoding Command

- 10-38 Using setRuntimeLogLevel Command

- 10-39 Using setShowRuntimeLoggerLogHostAddr Command

- 10-40 Using setShowRuntimeLoggerLogHostId Command

- 10-41 Using setShowRuntimeLoggerLogMsgClassPath Command

- 10-42 Using setShowRuntimeLoggerLogMsgLogLevel Command

- 10-43 Using setShowRuntimeLoggerLogUserId Command

- 10-44 Using settingsToString Command

- 10-45 Using showAllJobLogFiles Command

List of Figures

- 1-1 Single Computer Topology for Oracle Database 11g Release 2

- 1-2 Two Computer Topology; Separate Client and Database Server Installations

- 1-3 Multiple Database Topology

- 1-4 Separate Client, Control Service Center, and Database Server Topology

- 1-5 Control Center Agent Topology

- 8-1 Oracle Warehouse Builder Configuration Management

- 11-1 Metadata Change Management Window

List of Tables

- 6-1 Repository Upgrade Paths for Oracle Warehouse Builder 10.1 and Earlier

- 11-1 Comparison of Snapshots and Metadata Loader

- 12-1 Import Mode Results

- 13-1 Privileges Required for the Execution of Operations

- A-1 Naming Oracle RAC Service Nodes

Oracle® Warehouse Builder

Installation and Administration Guide

11g Release 2 (11.2)

E17130-05

September 2011

Oracle Warehouse Builder Installation and Administration Guide, 11g Release 2 (11.2)

E17130-05

Copyright © 2000, 2011, Oracle and/or its affiliates. All rights reserved.

Primary Author: Richa Agarwala

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, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

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 on 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. 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.

This program contains Batik version 1.6.

Apache License

Version 2.0, January 2004

http://www.apache.org/licenses/

For additional information about the terms and conditions, search for "Apache License" in Oracle Warehouse Builder online help.

Preface

This section contains the following topics:

- Audience

- Documentation Accessibility

- Related Documents

- Conventions

Audience

This document is intended for all persons responsible for installing Oracle Warehouse Builder, including:

- Data warehouse administrators

- System administrators

- Data warehouse and ETL developers

- Other MIS professionals

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 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 Documents

For more information, see the following documents in the Oracle Database 11g  Release 2 documentation set:

- Oracle Warehouse Builder Release Notes

- Oracle Warehouse Builder Concepts

- Oracle Warehouse Builder Sources and Targets Guide

- Oracle Warehouse Builder Data Modeling, ETL, and Data Quality Guide

- Oracle Warehouse Builder API and Scripting Reference

Conventions

The following text conventions are used in this document:

Convention

Meaning

boldface

Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary.

italic

Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.

monospace

Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

Part I

Installing and Configuring Oracle Warehouse Builder

This part contains the following sections:

- Chapter 1, "Overview of Installation and Configuration Architecture"

- Chapter 2, "Installing Oracle Warehouse Builder on the Server"

- Chapter 3, "Configuring Oracle Warehouse Builder for Windows"

- Chapter 4, "Configuring Oracle Warehouse Builder for Linux"

- Chapter 5, "Uninstalling Oracle Warehouse Builder"

- Chapter 6, "Moving to Oracle Warehouse Builder 11.2 from Earlier Releases"

- Chapter 7, "Configuring Repository Browser, Control Center Agent, and Other Components"

1 Overview of Installation and Configuration Architecture

This section discusses the architecture and components of Oracle Warehouse Builder and provides installation and configuration procedures.

This section includes the following topics:

- "Choosing an Appropriate Installation Configuration"

- "Architecture and Components of Oracle Warehouse Builder"

- "About the Check for Updates Wizard for Oracle Warehouse Builder"

Choosing an Appropriate Installation Configuration

Depending on the business needs of your organization, you may be implementing different types of Oracle Warehouse Builder installations:

- The primary installation of Oracle Warehouse Builder, which includes the installation and configuration of the main design repository.

- Optional installations on client computers where developers and administrators run Oracle Warehouse Builder client software, which do not contain a repository.

- Optional installations on hosts that run the Control Center Agent service, but do not contain a repository.

- Optional installations on database server hosts, where ETL jobs run and where the repository stores only run-time data.

See Also:

- "Architecture and Components of Oracle Warehouse Builder" for an overview of examples of various common topologies.

- Chapter 2, "Installing Oracle Warehouse Builder on the Server" for the software installation tasks.

- Chapter 3, "Configuring Oracle Warehouse Builder for Windows"

- Chapter 4, "Configuring Oracle Warehouse Builder for Linux"

Architecture and Components of Oracle Warehouse Builder

This section describes some common installation configurations, and shows how the various components interact. The primary Oracle Warehouse Builder components include:

- The Oracle Warehouse Builder Client (which includes the Design Center and the Control Center Manager)

- The Oracle Warehouse Builder Browser

- Control Center Service

- Control Center Agent

- The Repository

See Also:
Oracle Warehouse Builder Concepts for conceptual information about Oracle Warehouse Builder components.

Depending on your business needs, there are many possible installation configurations. The five most common topologies, that are illustrated in this section, are:

- "Single Computer Topology"

- "Separate Client and Database Server Topology"

- "Multiple Database Topology"

- "Separate Client, Control Center Service, and Database Server Topology"

- "Control Center Agent Topology"

Note:
In any of these topologies, it is typical to have multiple design clients. For example, each Oracle Warehouse Builder developer or administrator usually has a corresponding, installed Oracle Warehouse Builder client, also called a design client.

Single Computer Topology

When everything is running on the same computer, the database home for Oracle Database 11g Release 2 contains all the components needed to run Oracle Warehouse Builder, as illustrated in Figure 1-1.

Figure 1-1 Single Computer Topology for Oracle Database 11g Release 2

Description of "Figure 1-1 Single Computer Topology for Oracle Database 11g Release 2"

See Also:

- "Configuring Oracle Warehouse Builder on Windows Installed as Part of Oracle Database 11g Release 2"

- "Configuring Oracle Warehouse Builder on Linux Installed as Part of Oracle Database 11g Release 2"

Separate Client and Database Server Topology

If separate computers are being used to run the client and to host the repository, then all computers must have Oracle Warehouse Builder software installed, as illustrated in Figure 1-2. For the database server installation, Oracle Database 11g Release 2 includes the necessary components. For the client, you must install the Oracle Warehouse Builder software from the standalone install.

Figure 1-2 Two Computer Topology; Separate Client and Database Server Installations

Description of "Figure 1-2 Two Computer Topology; Separate Client and Database Server Installations"

See Also:
"Working with Oracle Warehouse Builder Standalone Install Package" for Oracle Warehouse Builder client installation procedures.

Multiple Database Topology

If a database on a separate computer is being used to run mappings designed on another database, then all computers must have the Oracle Warehouse Builder software installed, as illustrated in Figure 1-3. For the database servers, the installation for Oracle Database 11g Release 2 includes the necessary components. For the client, you must install Oracle Warehouse Builder software from the standalone install.

You must prepare Oracle Warehouse Builder repository on all database server computers. As illustrated in Figure 1-3, one acts as the design repository (Server1). The additional servers where mappings run, each have their own repository (shown as Server2), which in this case functions as a run-time repository. The Control Center Service on the execution database server deploys and runs the code.

Figure 1-3 Multiple Database Topology

Description of "Figure 1-3 Multiple Database Topology"

Separate Client, Control Center Service, and Database Server Topology

If Oracle Warehouse Builder client, the Control Center Service, and the repository run on different computers, then all these computers must have Oracle Warehouse Builder software installed, as illustrated in Figure 1-4. For the database server, the installation media for Oracle Database 11g Release 2 includes the necessary components. For the client, you must install Oracle Warehouse Builder software from the standalone install image. For the Control Center Service, you can use either type of installation. However, Oracle recommends that you use the standalone image because it installs only the components that Oracle Warehouse Builder requires.

Figure 1-4 Separate Client, Control Service Center, and Database Server Topology

Description of "Figure 1-4 Separate Client, Control Service Center, and Database Server Topology"

See Also:

- "Installing Oracle Warehouse Builder on Oracle Database 11g Release 2"

- "Installing Oracle Warehouse Builder in Oracle RAC Environments"

- "Working with Oracle Warehouse Builder Standalone Install Package" for Oracle Warehouse Builder client installation procedures.

Control Center Agent Topology

If separate computers are used to run client, the Control Center Agent service (CCA), and the repository, then all computers used to deploy or run Oracle Warehouse Builder code must have installed Oracle Warehouse Builder software, as illustrated in Figure 1-5. For the database server, the installation for Oracle Database 11g Release 2 includes the necessary components. For the client, you must install Oracle Warehouse Builder software from the standalone install image. For the Control Center Agent service, you can use either install. However, because the standalone image only installs Oracle Warehouse Builder-required components, Oracle recommends this option.

In some deployments, a Control Center Service is required on a host that does not have an Oracle Database installed. For example, if you use code template-based ETL mappings where part of the mapping executes on a non-Oracle database, then you can run a Control Center Agent on that non-Oracle database host. In such a case, you can install Oracle Warehouse Builder software on the non-Oracle database host.

Also note that:

- On the non-Oracle database host, the only component of Oracle Warehouse Builder software that is used is the Control Center Agent. The rest of the software is present but not used.

- The CCA may be located with Oracle Warehouse Builder client or Server1, in which case no additional installation would be necessary.

- In Figure 1-5, the Map1 has three execution units (a, b, c). The first two are Load Code Templates (LCTs) and the other one is an Oracle Target Code Template.

Figure 1-5 Control Center Agent Topology

Description of "Figure 1-5 Control Center Agent Topology"

See Also:

- Chapter 2, "Installing Oracle Warehouse Builder on the Server"

- Chapter 7, "Configuring Repository Browser, Control Center Agent, and Other Components"

About the Check for Updates Wizard for Oracle Warehouse Builder

Oracle Warehouse Builder provides the Check for Updates wizard within Design Center to simplify locating and downloading new resources for Oracle Warehouse Builder as follows:

- Links to updated release notes, white papers, sample code, and other information resources.

- New code templates, platform definitions and, drivers to extend Oracle Warehouse Builder for new sources and targets.

- New experts, scripts, and other utilities that enhance Oracle Warehouse Builder or help address specific use cases.

Resources delivered through the Check for Updates wizard may consist of links to My Oracle Support, downloadable documents, or zip archives. Installation instructions are included for client-side and server-side components with each resource as needed.

See Also:

- My Oracle Support at https://support.oracle.com and search on Oracle Warehouse Builder

- The product download page on Oracle Technology Network at http://www.oracle.com/technetwork/indexes/downloads/index.html

Note:
Oracle Warehouse Builder Repository Assistant can be started from OWB_HOME/owb/bin/unix/reposinst.sh on Linux or OWB_HOME\owb\bin\windows\reposinst.bat on Windows.

2 Installing Oracle Warehouse Builder on the Server

This section describes how to install Oracle Warehouse Builder on the server.

This section includes the following topics:

- "Installing Oracle Warehouse Builder on Oracle Database 11g Release 2"

- "Working with Oracle Warehouse Builder Standalone Install Package"

- "Installing Oracle Warehouse Builder Through Oracle Universal Installer"

- "Installing Oracle Warehouse Builder in Oracle RAC Environments"

- "Performing a Silent Install and Using Response Values"

- "After the Installation is Complete"

Installing Oracle Warehouse Builder on Oracle Database 11g Release 2

Oracle Warehouse Builder is part of the standard installation on all hosts running Oracle Database 11g Release 2. When Oracle Database is installed, you must only unlock the OWBSYS and OWBSYS_AUDIT accounts. The OWBSYS schema contains all Oracle Warehouse Builder repository metadata, and the OWBSYS_AUDIT schema is used by the Oracle Warehouse Builder Control Center Agent to access the heterogeneous execution audit tables of the OWBSYS schema.

Managing Optional Features for Oracle Warehouse Builder Installations

Although many features in Oracle Warehouse Builder are included in Oracle Database licenses, some features may require additional licensing. As an administrator, you can assist in managing license compliance by enabling or restricting user access to optional features. The management of optional features as described here is entirely voluntary.

When you first implement an Oracle Warehouse Builder repository, all optional features are enabled by default. You can modify these settings when you create the first workspace for the repository or you can modify the settings at a later time.

To manage the usage of optional features

1. Start the Repository Assistant. Select Start, Programs, ORACLE_HOME, Warehouse Builder, and then Administration.

2. If you are creating the first workshops for the repository, then the Repository Assistant automatically displays the Enable Optional Features page.
If you are modifying an existing repository, then on the Choose Operation page, select Manage Optional Features.

3. Select the options you want to make available to Oracle Warehouse Builder users.
The selections you make are enforced repository-wide and apply to all users. If a user is logged into Oracle Warehouse Builder client when you make changes on the Enable Optional Features page, then the changes are enforced for that user the next time they log in to the client.

Note:
For more information about each option, refer to the appropriate Oracle licensing information guide, listed on Oracle Technology Network at http://www.oracle.com/technetwork/developer-tools/warehouse/overview/index.html

Working with Oracle Warehouse Builder Standalone Install Package

There are several situations when you must download and install the Oracle Warehouse Builder 11g Release 2 standalone install package:

- You are installing Oracle Warehouse Builder 11.2 and hosting an Oracle Warehouse Builder Repository on an earlier release:
Oracle Database 10g Release 1, Oracle Database 10g Release 2,

or

Oracle Database 11g Release 1.

- You run the Oracle Warehouse Builder 11.2 Design Client on a developer's computer.

- You are installing Oracle Warehouse Builder 11.2 on a computer that runs the Control Center Agent.

To obtain Oracle Warehouse Builder Standalone Software:

1. Navigate the browser to the following URL:

http://www.oracle.com/technetwork/developer-tools/warehouse/overview/index.html/

2. On the right side of the page, click All Releases and Platforms.
Description of the illustration download_01.gif

3. Under Oracle Warehouse Builder Downloads, select Accept for the licence agreement.
Description of the illustration download_03.gif

The system displays the following message: "Thank you for accepting the OTN License Agreement; you may now download this software."

4. Under the Standalone Software download, click the down arrow beside the platform of your choice to download the zip file that contains Oracle Warehouse Builder.
On Windows: choose the Microsoft Windows option.

On Linux: choose the Linux x86 option.

Description of the illustration download_04.gif

5. When the download is complete, extract the zip file into a temporary directory. For example,
On Windows: use C:\temp\OWB.

On Linux: use /temp/OWB.

Installing Oracle Warehouse Builder Through Oracle Universal Installer

After you obtain the standalone installation files for Oracle Warehouse Builder and extract them, you must install the software.

To install Oracle Warehouse Builder using Oracle Universal Installer:

1. In Windows Explorer, navigate to the directory that contains the extracted Oracle Warehouse Builder installation files. In this discussion the sample directory is C:\temp\OWB.

2. Click the setup.bat file to start the Universal Installer.
Description of the illustration install_01.gif

3. On the Welcome screen, click Next.
Description of the illustration install_02.gif

4. On the Specify Home Details screen, specify a new Oracle home:

- Enter the Oracle home Name, for example, OWB112.

- Enter or browse to Path C:\.

- Click Next.

Description of the illustration install_03.gif

Tip:
To ensure a successful installation:

- Do not use an existing Oracle home.

- Do not use any spaces in the directory path.

5. [Optional] On the Customer Support Email screen, enter the Email and Password for your My Oracle Support account.
Click Next.

Description of the illustration install_08.gif

6. On the Summary screen, click Install.
Description of the illustration install_04.gif

7. The Install screen shows progress during the installation process.
Description of the illustration install_05.gif

8. At the End of Installation screen, click Exit. The Exit message appears asking if you really want to exit.
Description of the illustration install_06.gif

9. In the Exit message, click Yes.
Description of the illustration install_07.gif

Installing Oracle Warehouse Builder in Oracle RAC Environments

The overall process for installing on an Oracle RAC environment is similar to the general process for installing a single-instance database. However, there are a few specific details to observe as noted in this section.

To install and configure Oracle Warehouse Builder for Oracle RAC:

1. Create the Oracle RAC environment as described in Oracle Real Application Clusters Installation Guide specific to your platform. Cross references to generic installation guides are given after the last step of this procedure.

2. If you have not done so, review the most recent Oracle Warehouse Builder Release Notes available with the installation media.

See Also:

- Note ID 810394.1 "Oracle RAC and Oracle Clusterware Starter Kit and Best Practices" on My Oracle Support at https://support.oracle.com

- Oracle Database Release 11.2 documentation library page at http://www.oracle.com/pls/db112/homepage

- The product download page on at http://www.oracle.com/technetwork/indexes/downloads/index.html

3. Prepare the host computers.
For each computer to host Oracle Warehouse Builder components, configure the tnsnames.ora file located in the OWB_HOME\owb\network\admin directory.

4. Configure tnsnames.ora for each Oracle Database server to be an Oracle Warehouse Builder data source or target. If you fail to configure tnsnames.ora for any host or database server, then you may encounter a repository connection error.

See Also:
"ORA-12154: TNS: Could not resolve service name." for troubleshooting.

5. (Optional.) If necessary, install Oracle Warehouse Builder standalone software. However, this is generally not necessary because Oracle Warehouse Builder is installed as part of every Oracle Database 11g Release 2 installation.

6. Create your first workspace within Oracle Warehouse Builder Repository. The Repository Assistant prompts you and guides you with procedures.
To start the Repository Assistant on Windows, from the Windows Start menu, select Programs and navigate to the Oracle product group you installed in the previous step. Select Oracle Warehouse Builder, Administration, and then Repository Assistant.

To start the Repository Assistant on UNIX, locate OWB_HOME/owb/bin/unix and run reposinst.sh.

7. Register each Oracle RAC node.
For each node, start the Repository Assistant and select the Advanced Set Up option. Connect to the node using Host:Port:Sid, where Host is the physical node name. Select the option for registering the Oracle RAC instance.

8. If the software is installed on separate disks, copy rtrepos.properties to each node in the cluster.
If you did not install to a shared disk, then you must manually copy the file OWB_HOME/owb/bin/admin/rtrepos.properties from the primary node to each node in the cluster.

9. Install the Oracle Warehouse Builder software on the client computers.
Repeat the procedure in "Installing Oracle Warehouse Builder on Oracle Database 11g Release 2" for each computer to be used as a client.

10. After completing the installation process, you can start all the Oracle Warehouse Builder components.
Because you can connect to Oracle Warehouse Builder repositories using a net service name, you can embed Oracle RAC properties into the connect string to use Oracle RAC capabilities such as connect time failover, load balancing on server and load balancing of connections.

11. Refer to, "Ensuring the Availability of Service Names for Oracle RAC Nodes".
The Control Center Service requires that service names for the individual nodes in the cluster be available. If these are not present after the Oracle RAC installation, then you must manually ensure the availability.

See Also:

- Oracle® Real Application Clusters Installation Guide for Linux and UNIX

- Oracle® Real Application Clusters Installation Guide for Microsoft Windows x64 (64-Bit)

- Oracle Universal Installer and OPatch User's Guide for Windows and UNIX

Installing Oracle Warehouse Builder on Each Node of a Cluster

Whether you are installing Oracle Warehouse Builder components onto a server or a client computer, you use the Oracle Universal Installer to install Oracle Warehouse Builder components.

For Oracle RAC, it is recommended that you install the Oracle Warehouse Builder components on each node of the cluster. The Control Center Service is required on to each node of the Oracle RAC cluster. You can achieve this in a single installation of the Oracle Warehouse Builder software if you install on a shared disk such as an OCFS or NTS shared disk.

Before starting Oracle Universal Installer, review and complete the "Checklist: Before Using the Universal Installer in an Oracle RAC Environment".

Checklist: Before Using the Universal Installer in an Oracle RAC Environment

This section contains additional points to address before starting the Universal Installer:

- If you have not done so, review the latest Oracle Warehouse Builder Release Notes at http://www.oracle.com/technetwork/index.html

- The installed location must be the same directory path if using separate OWB_HOME installed disks, that is, local physical disks on each server.

- Close all other open applications.

For Windows Users Installing in an Oracle RAC Environment

To run the Oracle Universal Installer in an Oracle RAC environment:

1. Ensure that you are logged on to your system as a member of the Administrators group.

2. Insert the Oracle Warehouse Builder CD-ROM.

3. If your computer supports the autorun feature, then the autorun window automatically starts Oracle Warehouse Builder installation.
If your computer does not support the autorun feature, locate the executable setup.exe in the root directory of the CD-ROM or downloaded software. Start the installer by starting the setup.exe program.

4. When prompted to specify the cluster node, you can select all hosts or the local node.
If you select local node, then you must install Oracle Warehouse Builder separately for each system unless installing to a shared disk.

5. When prompted, specify a home directory to be used only for Oracle Warehouse Builder installation.
For example, specify a path such as C:\oracle\owb11_2.

For the sake of brevity, the path you specify in this step is referred to as OWB_HOME throughout this guide.

6. Follow the on screen instructions.

When the software installation completes successfully, you can continue with the next step in "Installing Oracle Warehouse Builder in Oracle RAC Environments".

For UNIX Users Installing in an Oracle RAC Environment

You can run Oracle Universal Installer from the CD-ROM. Do not run Oracle Universal Installer while the CD-ROM directory is the current directory because you cannot later unmount the next CD-ROM when prompted to do so.

To run the Oracle Universal Installer in an Oracle RAC environment:

1. To enable clusterware installation, ensure that you run an interactive secure shell such as /bin/ssh and have host user equivalency to all nodes.

2. Log in as the operating system user of the Oracle Database.
For example, log in as the oracle user.

Be sure you are not logged in as the root user when you start Oracle Universal Installer. If you log in as root user when you start Oracle Universal Installer, then only the root user has permissions to manage Oracle Warehouse Builder.

3. Start the installer by entering the following at the prompt:
cd mount_point

./runInstaller

4. When prompted to specify the cluster node, you can select all hosts or the local node.
If you select local node, then you must install Oracle Warehouse Builder separately for each system unless installing to a shared disk.

5. As the installation proceeds, the Oracle Universal Installer prompts you to run several scripts. You must switch users and run the script as root.

When the software installation completes successfully, you can continue with the next step in "Installing Oracle Warehouse Builder on Oracle Database 11g Release 2".

Ensuring the Availability of Service Names for Oracle RAC Nodes

1. List all of the instance or node names in the cluster. Issue the following command:
srvctl config database -d dbname

where dbname is the unique database name as specified by the initialization parameter db_name.

2. For a given instance, instn, add a service with the following command:
srvctl add service -d dbname -s instn -r instn

The resulting service name is instn.clusterdomainname. For example, if the instance name is abcdef1, then the service name could be abcdef1.example.com.

3. For a given instance, instn, start the service with the following command:
srvctl start service -d dbname -s instn

4. For a given instance, instn, verify the service is running with the following command:
srvctl status service -d dbname -s instn

5. Complete steps 2 through 4 for each node.

Performing a Silent Install and Using Response Values

An Oracle Universal Installer silent installation runs in the background and does not require input from the user. Instead of prompting the user to select a series of installation options, the software uses a pre-defined set of options stored in a response file or passed on the command line.

A response file specifies the information normally provided by the user to Oracle Universal Installer interface during an interactive installation session. Each answer is stored as a value for a variable identified in the response file. For example, values for Oracle home or install type can be set automatically within the response file.The response file template for the installation of your product can be found on your stage (CD-ROM) under the root_of_CD/response directory, such as:

Products.xml_Location/Response/product.installtype.rsp

To perform a silent installation of Oracle Warehouse Builder

- Open a Command window and navigate to the directory containing the response file that is used for the silent installation. Use the following command to start the silent installation:
On Windows, enter setup -responseFile filename optional_parameters

On Linux, enter runInstaller -responseFile filename optional_parameters

For this procedure, filename represents the name of the response file (including the complete path) and optional_parameters represents the parameters used for the silent installation.

After the Installation is Complete

After Oracle Warehouse Builder software is installed on your computer, you must configure it.

For steps on configuring Oracle Warehouse Builder on Linux, see Chapter 4, "Configuring Oracle Warehouse Builder for Linux".

For steps on configuring Oracle Warehouse Builder on Microsoft Windows, see Chapter 3, "Configuring Oracle Warehouse Builder for Windows".

3 Configuring Oracle Warehouse Builder for Windows

This section describes how to configure Oracle Warehouse Builder on Windows platforms.

This section includes the following topics:

- "Configuring Oracle Warehouse Builder on Windows Installed as Part of Oracle Database 11g Release 2"

- "Configuring Oracle Warehouse Builder on Windows Installed as a Standalone Instance"

- "Creating the First Workspace in the Repository on Windows"

Note:
The initial installation of Oracle Warehouse Builder must be on the computer that hosts the Oracle Warehouse Builder Repository.

Configuring Oracle Warehouse Builder on Windows Installed as Part of Oracle Database 11g Release 2

Oracle Warehouse Builder is part of every database installation on hosts running Oracle Database 11g Release 2.

After Oracle Database 11g Release 2 is installed, you must unlock two accounts: OWBSYS and OWBSYS_AUDIT.

There are no additional installation tasks. However, you must configure Oracle Workflow to use process flows in Oracle Warehouse Builder.

See Also:
"Integrating with Oracle Workflow"

To unlock OWBSYS and OWBSYS_AUDIT accounts:

1. At the command prompt, start SQL*Plus:

C:\> sqlplus

2. When prompted for user name, log in as a user with administrative privileges.

Enter user-name: sys as sysdba
Enter password: password

Connected to:
Oracle Database 11g Enterprise Edition Release 11.2 - Production
With the Partitioning, OLAP and Data Mining options

3. Unlock the OWBSYS user account, and set its new password:

SQL> alter user owbsys identified by password account unlock;

User altered.

4. Unlock the OWBSYS_AUDIT user account, and set its new password:

SQL> alter user owbsys_audit identified by password account unlock;

User altered.

Configuring Oracle Warehouse Builder on Windows Installed as a Standalone Instance

This section contains the following topics:

- "About Configuring Oracle Warehouse Builder Installed as a Standalone Instance"

- "Cleaning an Oracle Warehouse Builder Repository"

- "Creating an OWBSYS Schema with Repository Objects"

- "Configuring the Control Center Service"

- "Unlocking the OWBSYS and OWBSYS_AUDIT Accounts"

- "Setting Oracle Warehouse Builder Home for Remote Installations"

About Configuring Oracle Warehouse Builder Installed as a Standalone Instance

To properly configure Oracle Warehouse Builder and its repository on a host that runs an earlier version of the database, such as Oracle Database 10g Release 2, you must:

- Ensure that the database is fully installed and working; if it is not, see Oracle Database Installation Guide for Microsoft Windows.

- Note the host name, the port, and Oracle service name of this database. The example here uses the following connection information: localhost:1521:orcl.

- Ensure that you have the user name and password for an account with SYSDBA privileges. The SYSDBA privilege is necessary for making changes to the basic configuration of Oracle Database, Oracle Warehouse Builder, and Oracle Warehouse Builder Repository.

To create an Oracle Warehouse Builder repository in your database, you must first create an OWBSYS schema, and then install repository objects within it. Oracle Warehouse Builder has command-level scripts to perform this task:

- The clean_owbsys.sql script drops the contents of any existing OWBSYS schema installations, but leaves the schema otherwise intact.

- The cat_owb.sql script checks if an OWBSYS schema exists, and creates it if necessary, and then installs the objects required by Oracle Warehouse Builder 11.2 repository.

- The reset_owbcc_home.sql script ensures that Oracle Warehouse Builder uses the 11.2 version of the Control Center Service.

- [Optional] The remote_owb_install.sql script, when executed on the server, ensures that a repository on a remote system can be installed; it sets the REMOTE_OWB_HOME variable for authentication by remote systems.

Starting with Oracle Warehouse Builder 11.1, the metadata repository is stored in the OWBSYS schema, inside a workspace. This contrasts with the terminology of Oracle Warehouse Builder 10.2, where a workspace corresponds to a repository.

Oracle Warehouse Builder repositories for version 11.2 and 11.1 cannot coexist on the same database; creating an 11.2 repository overwrites the contents of the 11.1 repository in the database. Oracle recommends that you back up the older Oracle Warehouse Builder repositories before installing the 11.2 repository or upgrading to the 11.2 repository.

Cleaning an Oracle Warehouse Builder Repository

To clean an existing Oracle Warehouse Builder repository:

1. On the Microsoft Windows desktop, click Start and select Run.

2. Start SQL*Plus:

C:> sqlplus

3. When prompted for user name, log in as owbsys user.

Enter user-name: owbsys
Enter password: password

Connected to:
Oracle Database 11g Enterprise Edition Release 11.2 - Production
With the Partitioning, OLAP and Data Mining options

4. Stop Oracle Warehouse Builder Control Center service.

SQL> @c:\OWB112\owb\rtp\sql\stop_service.sql

See "stop_service" for more information.

5. Connect as user with administrative privileges:

SQL> connect sys as sysdba
Enter password: password

6. Run the clean_owbsys.sql script to drop all the objects in the existing OWBSYS schema:

SQL> @C:\OWB112\owb\UnifiedRepos\clean_owbsys.sql

Creating an OWBSYS Schema with Repository Objects

The process of creating (or refreshing) an OWBSYS schema generates the corresponding locked user account within the specified tablespace; in this example, the tablespace is USERS. When the script completes, you must unlock the account and set its password. The instructions in "Configuring Oracle Warehouse Builder on Windows Installed as Part of Oracle Database 11g Release 2" show how to unlock OWBSYS and OWBSYS_AUDIT accounts. OWBSYS schema is populated only when you run the Repository Assistant for the first time and create the first workspace in the repository.

See Also:
"Configuring Oracle Warehouse Builder for Oracle RAC"

To set-up an OWBSYS schema with repository objects:

1. On the Microsoft Windows desktop, click Start and select Run.

2. At the command prompt, start SQL*Plus:

C:\>sqlplus

3. When prompted for user name, log in as a user with administrative privileges.

Enter user-name: sys as sysdba
Enter password: password

Connected to:
Oracle Database 11g Enterprise Edition Release 11.2 - Production
With the Partitioning, OLAP and Data Mining options

4. Run the cat_owb.sql script to set up OWBSYS in a tablespace in your database. For example, this command sets up OWBSYS in the USERS tablespace:

SQL> @C:\OWB112\owb\UnifiedRepos\cat_owb.sql USERS

Configuring the Control Center Service

If you are installing Oracle Warehouse Builder 11.2 on an older Oracle Database release, or if you integrating Oracle Warehouse Builder with Oracle Business Intelligence Standard Edition (Oracle Discoverer), you must run the reset_owbcc_home.sql script to ensure that the Control Center Service functions correctly.

To configure the Control Center service:

1. In Windows Explorer, open the directory for the Oracle home of Oracle Warehouse Builder 11.2 to confirm the correct path for the Oracle home, paying particular attention to capitalization. In this example, the path is C:\OWB112.
While Windows is generally case insensitive, the path entered in the next steps must be an exact match to Oracle Warehouse Builder home directory, as displayed in the Windows Explorer address bar. To avoid errors, copy and paste the path.

2. On the Microsoft Windows desktop, click Start and select Run.

3. At the command prompt, start SQL*Plus:

C:\> sqlplus

4. When prompted for user name, log in as a user with administrative privileges.

Enter user-name: sys as sysdba
Enter password: password

Connected to:
Oracle Database 11g Enterprise Edition Release 11.2 - Production
With the Partitioning, OLAP and Data Mining options

5. Run the reset_owbcc_home.sql script to force the Control Center service to run from Oracle Warehouse Builder 11.2 installation:

SQL> @C:\OWB112\owb\UnifiedRepos\reset_owbcc_home.sql C:\OWB112

Unlocking the OWBSYS and OWBSYS_AUDIT Accounts

To unlock OWBSYS and OWBSYS_AUDIT accounts:

1. On the Microsoft Windows desktop, click Start and select Run.

2. At the command prompt, start SQL*Plus:

C:\>sqlplus

3. When prompted for user name, log in as a user with administrative privileges.

Enter user-name: sys as sysdba
Enter password: password

Connected to:
Oracle Database 11g Enterprise Edition Release 11.2 - Production
With the Partitioning, OLAP and Data Mining options

4. Unlock the OWBSYS user account, and set its new password:

SQL> alter user owbsys identified by password account unlock;

User altered.

5. Unlock the OWBSYS_AUDIT user account, and set its new password:

SQL> alter user owbsys_audit identified by password account unlock;

User altered.

Configuring Oracle Workflow to Support Oracle Warehouse Builder Process Flows

Using process flows requires that you configure Oracle Workflow for use with Oracle Warehouse Builder. See "Integrating with Oracle Workflow" for details on configuring Oracle Workflow.

Setting Oracle Warehouse Builder Home for Remote Installations

You must create a database directory OWB_REMOTE_ADMIN that is accessed by remote installations, so they can read the server's OWB_HOME/owb/bin/admin directory.

1. On the Microsoft Windows desktop, click Start and select Run.

2. At the command prompt, start SQL*Plus:

C:\> sqlplus

3. When prompted for user name, log in as a user with administrative privileges.

Enter user-name: sys as sysdba
Enter password: password

Connected to:
Oracle Database 11g Enterprise Edition Release 11.2 - Production
With the Partitioning, OLAP and Data Mining options

4. Set the OWB_REMOTE_HOME variable using script remote_owb_install.sql:

SQL> @remote_owb_install.sql OWB_REMOTE_HOME

Creating the First Workspace in the Repository on Windows

To use a repository, you must define an initial workspace, and the owner of that workspace. The following instructions use the Repository Assistant.

To create a workspace:

1. Start the repository assistant from the Start menu, selecting Program Files, then Oracle - OWB112, then Warehouse Builder, then Administration, then Repository Assistant.
Description of the illustration workspace_01.gif

2. On the Welcome screen of the Repository assistant, click Next.
Description of the illustration workspace_02.gif

3. On the Database Information screen, enter the connection information (Host Name, Port Number, and Oracle Service Name) for the repository database, and click Next.
Description of the illustration workspace_03.gif

4. On the Choose Operation screen, select Manage Warehouse Builder workspaces. Click Next.
Description of the illustration workspace_04.gif

5. On the Choose Workspace Operations screen, select Create a New Warehouse Builder workspace. Click Next.
Description of the illustration workspace_05.gif

6. On the New or Existing User screen, select Create a workspace with a new workspace owner. Click Next.
Description of the illustration workspace_06.gif

7. On the DBA Information screen, enter the User Name of a user with a SYS privilege, and that user's Password.
Click Next.

Description of the illustration workspace_07.gif

8. In the Workspace Owner (New) screen, enter the following:

- Workspace Owner's User Name (wks_owner1)

- Workspace Owner's Password

- Workspace Owner's Password Confirmation

- Workspace Name (wks1) (Workspace names cannot contain spaces)

Click Next.

Description of the illustration workspace_08.gif

9. On the OWBSYS Information screen, enter the OWBSYS Password.
Click Next.

Description of the illustration workspace_09.gif

10. [Optional] For remote installations (when you the schema is on a remote system), the system performs the verification of versions, and displays the dialog "Found OWB software with the compatible version installed locally on the database server computer with path REMOTE_OWB_HOME."
If the version is either incompatible or cannot be found, then the system displays the dialog "OWB software with the compatible version must be installed locally on the database server computer". If it is installed, acquire the DBA user credentials, and run the remote_owb_install.sql script on the Oracle Database server computer, as described in "Setting Oracle Warehouse Builder Home for Remote Installations".

11. On the Select Tablespaces screen, enter the following:

- Tablespace for Data (USERS, or the name of the desired tablespace)

- Tablespace for Indexes (USERS, or the name of the same tablespace)

- Tablespace for Temporary Data (TEMP)

- Tablespace for Snapshots (USERS, or the name of the same tablespace)

Click Next.

This step enables you to change the default tablespace details. Oracle Warehouse Builder repository is stored in the OWBSYS schema, but you must identify what tablespaces are used to store OWBSYS and certain other objects, like snapshots. You may choose tablespaces other than USERS, depending on your storage management strategy.

Description of the illustration workspace_10.gif

12. On the Select Languages screen, select the Base Language from the menu.
[Optional] You may also select additional Display Languages from the list of Available languages on the left-hand side, and move them to the list of Selected languages on the right side.

Click Next.

Description of the illustration workspace_11.gif

13. On the Workspace Users (Optional) screen, select the appropriate existing users from the Available list add them to the Selected list.
[Optional] Click Create New User to make new users who can access Oracle Warehouse Builder. This takes you to step 14.

Click Next. This takes you to step 16.

Description of the illustration workspace_12.gif

14. [Optional] In the Create New Database User screen, enter the following:

- User Name (demo_user)

- Password

- Re-enter Password

Click OK.

DBA User Name (system) and DBA User Password are disabled fields and cannot be edited.

Description of the illustration workspace_13.gif

15. In the Workspace Users (Optional) screen, click Next.
Description of the illustration workspace_14.gif

16. On the Summary screen, click Finish.

Description of the illustration workspace_15.gif

17. After the Installation Result screen appears, click OK.
Description of the illustration workspace_16.gif

4 Configuring Oracle Warehouse Builder for Linux

This section describes how to configure Oracle Warehouse Builder on Linux platforms.

This section includes the following topics:

- "Configuring Oracle Warehouse Builder on Linux Installed as Part of Oracle Database 11g Release 2"

- "Configuring Oracle Warehouse Builder on Linux Installed as a Standalone Instance"

- "Creating the First Workspace in the Repository on Linux"

Note:
The initial installation of Oracle Warehouse Builder must be made on the computer that hosts Oracle Warehouse Builder Repository.

Configuring Oracle Warehouse Builder on Linux Installed as Part of Oracle Database 11g Release 2

Oracle Warehouse Builder is part of every database installation on hosts running Oracle Database 11g Release 2.

After Oracle Database 11g Release 2 is installed, you only have to unlock two accounts: OWBSYS and OWBSYS_AUDIT.

There are no additional installation tasks. However, you must configure Oracle Workflow to use process flows.

See Also:
"Integrating with Oracle Workflow"

To unlock OWBSYS and OWBSYS_AUDIT accounts:

1. At the command prompt, start SQL*Plus:

C:\> sqlplus

2. When prompted for user name, log in as a user with administrative privileges.

Enter user-name: sys as sysdba
Enter password: password

Connected to:
Oracle Database 11g Enterprise Edition Release 11.2 - Production
With the Partitioning, OLAP and Data Mining options

3. Unlock the OWBSYS user account, and set its new password:

SQL> alter user owbsys identified by password account unlock;

User altered.

4. Unlock the OWBSYS_AUDIT user account, and set its new password:

SQL> alter user owbsys_audit identified by password account unlock;

User altered.

Configuring Oracle Warehouse Builder on Linux Installed as a Standalone Instance

This section contains the following topics:

- "About Configuring Oracle Warehouse Builder Installed as a Standalone Instance"

- "Cleaning an Oracle Warehouse Builder Repository"

- "Creating an OWBSYS Schema with Repository Objects"

- "Configuring the Control Center Service"

- "Unlocking the OWBSYS and OWBSYS_AUDIT Accounts"

About Configuring Oracle Warehouse Builder Installed as a Standalone Instance

To properly configure Oracle Warehouse Builder and its repository on a host that runs an earlier version of the database, such as Oracle Database 10g Release 2, you must:

- Ensure that the database is fully installed and working; if it is not, see Oracle Database Installation Guide for Linux.

- Note of the host name, the port, and Oracle service name of this database. The example here uses the following connection information: localhost:1521:orcl.

- Ensure that you have user name and password for an account with SYSDBA privileges. The SYSDBA privilege has the necessary privileges for making changes to the basic configuration of Oracle Database, Oracle Warehouse Builder, and Oracle Warehouse Builder Repository.

To create an Oracle Warehouse Builder repository in your database, you must first create an OWBSYS schema, and then install repository objects within it. Oracle Warehouse Builder has command-level scripts to perform this task:

- The clean_owbsys.sql script drops the contents of any existing OWBSYS schema installations, but leaves the schema otherwise intact.

- The cat_owb.sql script checks if an OWBSYS schema exists, and creates it if necessary, and then installs the objects required by Oracle Warehouse Builder 11.2 repository.

- The reset_owbcc_home.sql script ensures that Oracle Warehouse Builder uses the 11.2 version of the Control Center Service.

- [Optional] The remote_owb_install.sql script, when executed on the server, ensures that a repository on a remote system can be installed; it sets the REMOTE_OWB_HOME variable for authentication by remote systems.

Starting with Oracle Warehouse Builder 11.1, the metadata repository is stored in the OWBSYS schema, inside a workspace. This contrasts with the terminology of Oracle Warehouse Builder 10.2, where a workspace corresponds to a repository.

Oracle Warehouse Builder repositories for version 11.2 and 11.1 cannot coexist on the same database; creating an 11.2 repository overwrites the contents of the 11.1 repository in the database. Oracle recommends that you back up the older Oracle Warehouse Builder repositories before installing the 11.2 repository or upgrading to the 11.2 repository.

Cleaning an Oracle Warehouse Builder Repository

To clean an existing Oracle Warehouse Builder Repository:

1. At the command prompt, start SQL*Plus:

C:\> sqlplus

2. When prompted for user name, log in as OWBSYS user.

Enter user-name: owbsys
Enter password: password

Connected to:
Oracle Database 11g Enterprise Edition Release 11.2 - Production
With the Partitioning, OLAP and Data Mining options

3. Stop Oracle Warehouse Builder Control Center service.

SQL> @OWB112/owb/rtp/sql/stop_service.sql

See "stop_service" for more information.

4. Connect as user with administrative privileges:

SQL> connect sys as sysdba
Enter password: password

5. Run the clean_owbsys.sql script to drop all the objects in the existing OWBSYS schema:

SQL> @OWB112/owb/UnifiedRepos/clean_owbsys.sql

Creating an OWBSYS Schema with Repository Objects

The process of creating (or refreshing) an OWBSYS schema generates the corresponding locked user account within the specified tablespace. In this example, the tablespace is USERS. When the script completes, you must unlock the account and set its password. The instructions in "Configuring Oracle Warehouse Builder on Linux Installed as Part of Oracle Database 11g Release 2" show how to unlock OWBSYS and OWBSYS_AUDIT accounts. The OWBSYS schema is populated only when you run the Repository Assistant for the first time and create the first workspace in the repository.

See Also:
"Configuring Oracle Warehouse Builder for Oracle RAC"

To set-up an OWBSYS schema with repository objects:

1. At the command prompt, start SQL*Plus:

C:\> sqlplus

2. When prompted for user name, log in as a user with administrative privileges.

Enter user-name: sys as sysdba
Enter password: password

Connected to:
Oracle Database 11g Enterprise Edition Release 11.2 - Production
With the Partitioning, OLAP and Data Mining options

3. Run the cat_owb.sql script to set up OWBSYS in a tablespace in your database. For example, this command sets up OWBSYS in the USERS tablespace:

SQL> @OWB112/owb/UnifiedRepos/cat_owb.sql USERS

Configuring the Control Center Service

If you are installing Oracle Warehouse Builder 11.2 on an older Oracle Database release, or if you integrating Oracle Warehouse Builder with Oracle Business Intelligence Standard Edition (Oracle Discoverer), you must run the reset_owbcc_home.sql script to ensure that the Control Center Service functions correctly.

To configure the Control Center service:

1. Confirm the correct Oracle home path, paying particular attention to capitalization. In this example, the path is OWB112.
The path entered in the next steps must be an exact match to the Oracle Warehouse Builder home directory, including letter case match.

2. At the command prompt, start SQL*Plus:

C:\> sqlplus

3. When prompted for user name, log in as a user with administrative privileges.

Enter user-name: sys as sysdba
Enter password: password

Connected to:
Oracle Database 11g Enterprise Edition Release 11.2 - Production
With the Partitioning, OLAP and Data Mining options

4. Run the reset_owbcc_home.sql script to force the Control Center Service to run from Oracle Warehouse Builder 11.2 installation:

SQL> @OWB112/owb/UnifiedRepos/reset_owbcc_home.sql OWB112

Unlocking the OWBSYS and OWBSYS_AUDIT Accounts

To unlock OWBSYS and OWBSYS_AUDIT accounts:

1. At the command prompt, start SQL*Plus:

C:\> sqlplus

2. When prompted for user name, log in as a user with administrative privileges.

Enter user-name: sys as sysdba
Enter password: password

Connected to:
Oracle Database 11g Enterprise Edition Release 11.2 - Production
With the Partitioning, OLAP and Data Mining options

3. Unlock the OWBSYS user account, and set its new password:

SQL> alter user owbsys identified by password account unlock;

User altered.

4. Unlock the OWBSYS_AUDIT user account, and set its new password:

SQL> alter user owbsys_audit identified by password account unlock;

User altered.

Configuring Oracle Workflow to Support Oracle Warehouse Builder Process Flows

Using process flows requires that you configure Oracle Workflow for use with Oracle Warehouse Builder. See "Integrating with Oracle Workflow" for details on configuring Oracle Workflow.

Setting the Oracle Warehouse Builder Home for Remote Installations

You must create a database directory OWB_REMOTE_ADMIN that is accessed by remote installations, so they can read the server's OWB_HOME/owb/bin/admin directory.

1. At the command prompt, start SQL*Plus:

C:\> sqlplus

2. When prompted for user name, log in as a user with administrative privileges.

Enter user-name: sys as sysdba
Enter password: password

Connected to:
Oracle Database 11g Enterprise Edition Release 11.2 - Production
With the Partitioning, OLAP and Data Mining options

3. Set the OWB_REMOTE_HOME variable using script remote_owb_install.sql:

SQL> @OWB112/owb/UnifiedRepos/remote_owb_install.sql OWB_REMOTE_HOME

Creating the First Workspace in the Repository on Linux

To use a repository, you must define an initial workspace, and the owner of that workspace. The following instructions use the Repository Assistant.

To create a workspace:

1. At the command prompt, navigate to the UNIX bin directory:

C:\> d OWB112/owb/bin/unix

C:\> pwd
OWB112/owb/bin/unix

2. Start the repository assistant.

C:\> ./reposinst.sh

3. On the Welcome screen of the Repository assistant, click Next.
Description of the illustration workspace_02.gif

4. On the Database Information screen, enter the connection information (Host Name, Port Number, and Oracle Service Name) for the repository database, and click Next.
Description of the illustration workspace_03.gif

5. On the Choose Operation screen, select Manage Warehouse Builder workspaces. Click Next.
Description of the illustration workspace_04.gif

6. On the Choose Workspace Operations screen, select Create a New Warehouse Builder workspace. Click Next.
Description of the illustration workspace_05.gif

7. On the New or Existing User screen, select Create a workspace with a new workspace owner. Click Next.
Description of the illustration workspace_06.gif

8. On the DBA Information screen, enter the User Name of a user with a CREATE USER privilege, and that user's Password.
Click Next.

Description of the illustration workspace_07.gif

9. In the Workspace Owner (New) screen, enter the following information:

- Workspace Owner's User Name (wks_owner1)

- Workspace Owner's Password

- Workspace Owner's Password Confirmation

- Workspace Name (wks1) (Workspace names cannot contain spaces)

Click Next.

Description of the illustration workspace_08.gif

10. In the OWBSYS Information screen, enter the OWBSYS Password. Click Next.
You need these credentials to seed the OWBSYS schema.

Description of the illustration workspace_09.gif

11. [Optional] For remote installations (when the schema is on a remote system), the system performs the verification of versions, and displays the message: "Found Oracle Warehouse Builder software with the compatible version installed locally on the database server with path REMOTE_OWB_HOME."
If the version is either incompatible or cannot be found, then the system displays the message: " Oracle Warehouse Builder software with the compatible version must be installed locally on the database server." If the compatible version is installed, then acquire the DBA user credentials and run the remote_owb_install.sql script from the system where Oracle Database is installed, as described in "Setting the Oracle Warehouse Builder Home for Remote Installations".

12. On the Select Tablespaces screen, enter the following information:

- Tablespace for Data (USERS, or the name of the desired tablespace)

- Tablespace for Indexes (USERS, or the name of the same tablespace)

- Tablespace for Temporary Data (TEMP)

- Tablespace for Snapshots (USERS, or the name of the same tablespace)

Click Next.

This step enables you to change the default tablespace details. Oracle Warehouse Builder Repository is stored in the OWBSYS schema, but you must identify what tablespaces are used to store OWBSYS and certain other objects, like snapshots. You may choose tablespaces other than USERS, depending on your storage management strategy.

Description of the illustration workspace_10.gif

13. On the Select Languages screen, select the Base Language from the menu.
[Optional] You may also select additional Display Languages from the list of Available languages on the left side, and move them to the list of Selected languages on the right side.

Click Next.

Description of the illustration workspace_11.gif

14. On the Workspace Users (Optional) screen, select the appropriate existing users from the Available list add them to the Selected list.
[Optional] Click Create New User to make new users who can access Oracle Warehouse Builder. This takes you to step 15.

Click Next. This takes you to step 17.

Description of the illustration workspace_12.gif

15. [Optional] In the Create New Database User screen, enter the following:

- User Name (demo_user)

- Password

- Re-enter Password

Click OK.

DBA User Name (system) and DBA User Password are disabled fields and cannot be edited.

Description of the illustration workspace_13.gif

16. In the Workspace Users (Optional) screen, click Next.
Description of the illustration workspace_14.gif

17. On the Summary screen, click Finish.

Description of the illustration workspace_15.gif

18. After the Installation Result screen appears, click OK.
Description of the illustration workspace_16.gif

5 Uninstalling Oracle Warehouse Builder

This section describes how to uninstall Oracle Warehouse Builder.

This section includes the following topics:

- "About Uninstalling Oracle Warehouse Builder"

- "Deleting the Workspace Users"

- "Deleting the Workspace"

- "Deleting the Schema Objects"

- "Deleting a Repository from an Oracle Database"

- "Uninstalling the Oracle Warehouse Builder Software"

About Uninstalling Oracle Warehouse Builder

You cannot uninstall Oracle Warehouse Builder in Oracle Database 11g Release 2.

To uninstall earlier versions of Oracle Warehouse Builder, you have two general options:

- Removing only the client components
To remove Oracle Warehouse Builder components from a host where there is no repository, follow the instructions in "Uninstalling the Oracle Warehouse Builder Software". To uninstall all Oracle Warehouse Builder components including the repository, then you must have SYSDBA privileges to the repository.

- Removing both server and client components from your environment
To remove all components, you must complete the following tasks, in that sequence. Otherwise, you may have to manually delete some components:

1. Use the Advanced Setup option in the Repository Assistant to delete all workspace users, as described in "Deleting the Workspace Users".

2. Use the Advanced Setup option in the Repository Assistant to delete the workspace owner, as described in "Deleting the Workspace".

3. [Optional] Delete the Oracle Warehouse Builder schema objects, as described in, "Deleting the Schema Objects".

4. Delete the repository, as described in, "Deleting a Repository from an Oracle Database".

5. Start the Universal Installer to uninstall the software components, as described in "Uninstalling the Oracle Warehouse Builder Software".

Deleting the Workspace Users

Before you can uninstall a workspace owner, you must first delete the associated workspace users. When you delete a workspace user, you un-register and remove the user from the repository. Deleting the user from Oracle Warehouse Builder repository does not delete or alter the corresponding user account in the Oracle Database.

To delete workspace users:

1. Start Oracle Warehouse Builder Repository Assistant.

On Windows, select Start, Programs, Oracle-OWB11.2, Oracle Warehouse Builder, Administration, and then click Repository Assistant.

Description of the illustration del_wksp_users_01.gif

On Linux, in the OWB_HOME/owb/bin/unix directory, run the reposinst.sh script.

2. On the Welcome screen, click Next.
Description of the illustration del_wksp_users_02.gif

3. On the Database Information page, enter the Host Name, Port Number, and Oracle Service Name. Click Next.

These details are automatically filled in based on the values entered in the install and configuration stage.

In this example, the values used are of LOCALHOST, 1521, and orcl, respectively.

Description of the illustration del_wksp_users_03.gif

4. On the Choose Operation screen, select Manage Warehouse Builder workspace users option.
Click Next.

Description of the illustration del_wksp_users_04.gif

5. On the Workspace Owner/Admin screen, enter the Workspace Owner / Admin User Name (wks_owner1), and Workspace Owner / Admin Password.
Click Next.

Description of the illustration del_wksp_users_05.gif

6. On the Workspaces screen, select the Workspace Name (WKS_OWNER1.WKS1).
Click Next.

Description of the illustration del_wksp_users_06.gif

7. On the Options (Workspace Users) screen, select Un-register of Warehouse Builder workspace users.
Click Next.

Description of the illustration del_wksp_users_07.gif

8. On the Select Workspace Users screen, move the users you want to delete from the Available list to the Selected list. Click Next.
Description of the illustration del_wksp_users_08.gif

9. In the Summary screen, click Finish.
Description of the illustration del_wksp_users_09.gif

10. On the Deinstallation Result screen, click OK.
Description of the illustration del_wksp_users_10.gif

Deleting the Workspace

After deleting the workspace users, you can delete the workspace. When you delete a workspace owner, you un-register and remove the owner from the repository. Deleting the owner from the repository does not delete or alter the owner account in the Oracle Database.

To delete the workspace:

1. Repeat steps 1 through 3 in "Deleting the Workspace Users".

2. On the Choose Operation screen, select Manage Warehouse Builder workspaces.
Click Next.

Description of the illustration del_wksp_users_11.gif

3. On the Choose Workspace Operations screen, select Drop and existing Warehouse Builder workspace.
Click Next.

Description of the illustration del_wksp_users_12.gif

4. On the Workspace Owner/Admin screen, enter the Workspace Owner / Admin User Name (wks_owner1), and Workspace Owner / Admin Password.
Click Next.

Description of the illustration del_wksp_users_05.gif

5. On the Workspaces screen, select the Workspace Name (WKS_OWNER.WKS1).
Click Next.

Description of the illustration del_wksp_users_06.gif

6. On the Summary screen, click Finish.
Description of the illustration del_wksp_users_14.gif

7. On the Deinstallation Result screen, click OK.
Description of the illustration del_wksp_users_15.gif

Deleting the Schema Objects

When you delete a workspace user or the workspace owner, you un-register and remove that owner from the repository. This operation, however, does not delete that user or owner, or alter the account in the Oracle Database.

To permanently delete the workspace users, workspace owners, and the Oracle Warehouse Builder-related roles and synonyms permanently from Oracle Database, use Oracle Enterprise Manager. To enable Oracle Warehouse Builder user to run Enterprise manager, you must grant the appropriate permissions.

To grant access to Enterprise Manager:

1. At the command prompt, start SQL*Plus.

C:\> sqlplus

2. When prompted for user name, log in as a user with administrative privileges.

Enter user-name: sys/as sysdba
Enter password: password

Connected to:
Oracle Database 11g Enterprise Edition Release 11.2 - Production
With the Partitioning, OLAP and Data Mining options

3. Use the GRANT command:

SQL> GRANT SELECT any dictionary to "&OWB repository user";

Deleting a Repository from an Oracle Database

To delete an Oracle Warehouse Builder 11g repository and associated objects from an Oracle Database 10g Release 2, use the SQL script clean_owbsys.sql, in the OWB_HOME/owb/UnifiedRepos directory.

These instructions are for deleting earlier Oracle Warehouse Builder installations. Oracle Warehouse Builder cannot be deleted from Oracle Database 11g Release 2 as the schemas remain; however, running the clean_owbsys.sql script removes all the objects inside the schema.

To delete the repository:

1. At the command prompt, start SQL*Plus:

C:\> sqlplus

2. When prompted for user name, log in as a user with administrative privileges.

Enter user-name: sys/as sysdba
Enter password: password

Connected to:
Oracle Database 11g Enterprise Edition Release 11.2 - Production
With the Partitioning, OLAP and Data Mining options

3. Run the clean_owbsys.sql script to drop the OWBSYS user and Oracle Warehouse Builder-related roles from the database:

SQL> @OWB112/owb/UnifiedRepos/clean_owbsys.sql C:/OWB112

If you previously used the Repository Assistant to create a workspace, or a workspace owner and database user, these they still exist in the database after running the clean_owbsys.sql script.

Uninstalling the Oracle Warehouse Builder Software

To uninstall Oracle Warehouse Builder software, you must use the Oracle Universal Installer.

Uninstalling Oracle Warehouse Builder deletes the files in OWB_HOME, namely the scripts necessary for cleaning up the schema and the repository. Therefore, this should be the last process you perform, after steps described in "Deleting the Schema Objects" and "Deleting a Repository from an Oracle Database".

To uninstall Oracle Warehouse Builder software:

1. Start Oracle Universal Installer.
On Windows, select Start, Programs, then select OWB_HOME, Oracle Installation Products, and then click Universal Installer.

Description of the illustration uninstall_01.gif

On Linux, run the script runInstaller.sh in the OWB_HOME/oui/bin directory.

2. On the Oracle Universal Installer: Welcome page, click Deinstall Products.

3. On the Inventory page, under the Contents tab, in the box titled "You have the following Oracle products installed," select the OWB home.
Click Remove.

4. On the Confirmation page, click Yes.
The uninstallation process begins.

5. After the process is complete, on the Inventory page, click Close.

6. On the Oracle Universal Installer: Welcome page, click Cancel.
This closes the Oracle Universal Installer.

6 Moving to Oracle Warehouse Builder 11.2 from Earlier Releases

Oracle Warehouse Builder enables you to upgrade repositories from Oracle Warehouse Builder 10gRelease 2 and Oracle Warehouse Builder 11g Release 1 to Oracle Warehouse Builder 11g Release 2.

This section describes the different methods of moving to Oracle Warehouse Builder Release 11.2 from earlier releases, the upgrade and migration paths and upgrade process, and changes to upgraded ETL design objects to make them compatible with Oracle Warehouse Builder Release 11.2.

This section includes the following topics:

- "Understanding MDL Migration and Repository Upgrades"

- "Choosing a Repository Upgrade Scenario"

- "In-Place Upgrade of Oracle Warehouse Builder 10g Release 2 or 11g Release 1 Repository to Oracle Warehouse Builder 11g Release 2"

- "Migrating the Repository to a Different Oracle Database Instance"

- "Upgrading Locations to Oracle Warehouse Builder Release 11.2"

- "Changes to Repository Objects When Moving to Oracle Warehouse Builder 11g Release 2"

Understanding MDL Migration and Repository Upgrades

The two ways to move projects from earlier releases into Oracle Warehouse Builder Release 11.2 are migrating objects and upgrading repositories.

This discussion uses the following definitions:

- Upgrading a repository is the process of taking an entire repository, including the control center audit data such as deployment and execution history, from an earlier Oracle Warehouse Builder release and moving it to Oracle Warehouse Builder 11.2. This process is performed from within Repository Assistant.

- Migrating objects, in moving between Oracle Warehouse Builder Releases, is the process of exporting existing Oracle Warehouse Builder design-time objects from an earlier Oracle Warehouse Builder release, and importing the resulting MDL file into Oracle Warehouse Builder Release 11.2. This process is performed from Oracle Warehouse Builder Design Center.

Choosing Between MDL Migration and Repository Upgrade

The Repository Assistant in Oracle Warehouse Builder Release 11.2 provides ways to upgrade Oracle Warehouse Builder Release 10.2 and Release 11.1 repositories directly. The advantages of upgrading an entire repository are:

- You can move up to Oracle Warehouse Builder Release 11.2 without regenerating code or redeploying your mappings, for maximum stability, then decide on objects to regenerate or redeploy based on whether you need specific Release 11.2 enhancements.

- Upgrading can bring forward all design-time and run-time audit metadata from the previous repository, such as the history of deployments and executions of your ETL mappings, process flows, and other objects.

- All projects and global objects in a repository are processed.

The advantages of migrating individual projects or other objects include:

- Speed, if you have large volumes of run-time metadata that you must preserve.

- Simplicity, in cases where the upgrade path for the complete repository is more complex than the migration path. In particular, Oracle Warehouse Builder Release 11.2 can directly import MDL for projects from Oracle Warehouse Builder 9.2 and 10.1, but cannot upgrade the entire repository from these earlier releases. For example, upgrading an entire repository from Oracle Warehouse Builder 10.1 or older may require creating one or more new Oracle Warehouse Builder environments from intermediate releases, to be used for these intermediate upgrades.

MDL Migration Paths

Oracle Warehouse Builder Release 11.2 can directly import MDL for projects or other objects from Oracle Warehouse Builder 9.2.0.n or higher. Importing metadata from MDL files from earlier releases is performed in Oracle Warehouse Builder Release 11.2 Design Center. Chapter 12, "Importing, Exporting, and Upgrading Metadata" describes the process. The process is like importing any other MDL file. However, you are prompted for a file name for an intermediate MDL file (which is your file upgraded to the new format for Oracle Warehouse Builder Release 11.2). This file is generated, saved at a location you specify, and then immediately imported.

For releases older than 9.2.0.n, the supported migration path requires an intermediate step:

1. Import the MDL to an intermediate 10.2.0.5 or 11.1.0.7 database. These versions should be able to read any older MDL.
The MDL file upgrade process is performed during the import process. Oracle Warehouse Builder generates an upgraded MDL file; you are prompted for a file name.

The file name writes the upgraded MDL file you specify, and is then imported into your intermediate database. You can ignore this and simply copy the intermediate file to a new location.

2. Import that upgraded MDL into Oracle Warehouse Builder 11.2 using Design Center, as described in Chapter 12, "Importing, Exporting, and Upgrading Metadata."

Note:
The latest 10.1, 10.2 or 11.1 patch release is strongly recommended for cases where an intermediate release is used in the upgrade path. In some cases, earlier patch releases may not import or upgrade metadata from all earlier releases of the product.

Repository Upgrade Paths from Oracle Warehouse Builder 10.1 or 9.n to Release 11.2

Oracle Warehouse Builder Release 11.2 can directly upgrade repositories from Oracle Warehouse Builder 10.2.0.n or Oracle Warehouse Builder 11.1.0.n. Repositories from older releases cannot be upgraded directly. Oracle Warehouse Builder 10.2 becomes an intermediate step in the upgrade path.

Oracle Warehouse Builder 10g Release 2 combined the separate design-time and run-time repositories from earlier releases into a single unified repository, which is used in all subsequent releases. Oracle Warehouse Builder 10g Release 2 Repository Assistant contains the functionality required to merge previously separate design-time and run-time repository contents from Oracle Warehouse Builder 10.1.0.4 into the new combined repository model. If your source is 9.2.0.n or earlier, then you must first upgrade to Oracle Warehouse Builder 10.1.0.4.

Therefore, if upgrading both run-time and design-time metadata from a 10.1 or earlier release, the stages required are:

- Prepare an Oracle Warehouse Builder 10.2 environment

- Upgrade the separate design-time and run-time repositories from the earlier releases into the combined Oracle Warehouse Builder 10.2 repository in that environment

- Upgrade the resulting 10.2 repository to Oracle Warehouse Builder 11.2.

The following table summarizes the repository upgrade paths for releases before Oracle Warehouse Builder 10.2:

Table 6-1 Repository Upgrade Paths for Oracle Warehouse Builder 10.1 and Earlier

Current Release

Repository Upgrade Path

10.1.0.n

To 10.2.0.n, then to 11.2

9.2.0.n or Older

To 10.1.0.4, then to 10.2.0.n, then to 11.2

To perform these repository upgrades, you require working environments for the intermediate versions on the upgrade path.

For example, if you are upgrading a 9.2 repository, you must set up an Oracle Warehouse Builder 10.1.0.4 environment and an Oracle Warehouse Builder Release 10.2.0.5 environment for use during the upgrade steps, then upgrade from Release 9.2 to Release 10.1.0.4 and upgrade the result to Oracle Warehouse Builder Release 10.2.0.5.

See the documentation for those older releases for details on the intermediate upgrades.

If you are moving to Oracle Warehouse Builder 11.2 from Oracle Warehouse Builder 10.1 or earlier, then it is usually simpler is to migrate objects on a project-by-project basis into a clean Oracle Warehouse Builder Release 11.2 workspace. Export the projects to MDL in Design Center using the process for those releases, and import the MDL objects into Oracle Warehouse Builder Release 11.2, using the steps in Chapter 12, "Importing, Exporting, and Upgrading Metadata."

Choosing a Repository Upgrade Scenario

The Repository Assistant for Oracle Warehouse Builder 11.2 supports two major upgrade scenarios:

- Repository upgrade through MDL files, where the complete repository from Oracle Warehouse Builder 10.2 or Oracle Warehouse Builder 11.1 is exported to an MDL file, and then that MDL file is later imported into a database with an Oracle Warehouse Builder 11.2 repository schema.

- An in-place repository upgrade, in which case the new Oracle Warehouse Builder 11.2 repository is immediately created in the same database where Oracle Warehouse Builder 10.2 or 11.1 repository was stored.

Note the following:

- Upgrading through MDL files is the only option when moving your entire repository to a new database. (Exporting the entire repository to MDL is also a good option for backing up the repository.)

- An in-place repository upgrade of Oracle Warehouse Builder 11.1 overwrites the Oracle Warehouse Builder 11.1 repository with Oracle Warehouse Builder 11.2 repository, because both are stored in the same repository schema.

- Internally, an in-place repository upgrade actually performs a repository export to MDL and repository import from MDL. The advantage of in-place repository upgrade is that the user performs fewer manual steps than in the upgrade through MDL files when targeting the same database.

In-Place Upgrade of Oracle Warehouse Builder 10g Release 2 or 11g Release 1 Repository to Oracle Warehouse Builder 11g Release 2

An in-place upgrade of an Oracle Warehouse Builder repository is the simplest method of a repository upgrade where the target Release 11.2 repository is stored in the same database instance that contained the source repository. You can perform an in-place upgrade of either Oracle Warehouse Builder 10g Release 2 or Oracle Warehouse Builder 11g Release 1 Repository that exists on the same database instance as your Oracle Database 11g Release 2 installation.

For Oracle Warehouse Builder 10g Release 2, Repository Assistant exports the specified repository to an MDL file, then imports that MDL file into a new Release 11.2 workspace in the OWBSYS schema in the same database. The workspace name is same as the schema that contained the 10g Release 2 repository.

For Oracle Warehouse Builder 11g Release 1, Repository Assistant exports the whole repository from the OWBSYS schema to an MDL file, drops all contents of Oracle Warehouse Builder 11g Release 1 repository (as if you had run clean_owbsys.sql), creates a new Oracle Warehouse Builder Release 11.2 repository in OWBSYS, and re-imports the repository from MDL.

Note:
If your target database has an Oracle Warehouse Builder 11g Release 1 OWBSYS schema, then back it up before starting the actual migration using the 11.2 Repository Assistant. This provides you a way to recover from any possible failures during the upgrade process. The process described in "Preparing for In-Place Repository Upgrade" overwrites the OWBSYS schema (if it exists) with Oracle Warehouse Builder 11.2 schema.

Preparing for In-Place Repository Upgrade

To perform the tasks in this section, you must have SYSADMIN privileges, that enables you to run prerequisite scripts.

Note:
Check the latest Oracle Warehouse Builder Release Notes at http://www.oracle.com/technetwork/developer-tools/warehouse/overview/index.html before starting the upgrade process.

The steps for preparing a repository for in-place repository upgrade are slightly different for Windows and Linux.

To prepare for an in-place repository upgrade on Windows

1. Ensure that you make a back-up copy of the OWBSYS schema, using the backup strategy employed in your organization.

2. On the Microsoft Windows desktop, click Start and select Run.

3. In the Run window, for Open, enter cmd.
Click OK.

4. At the command prompt, start SQL*Plus:

C:\> sqlplus

5. Connect as a user with administrative privileges:

SQL> connect sys as sysdba
Enter password: password

6. You have two options for the OWBSYS schema:

- If the OWBSYS schema does not exist on the Oracle Database instance, then run the cat_owb.sql script to create it:

SQL> @C:\OWB112\owb\UnifiedRepos\cat_owb.sql

- If the OWBSYS schema exists on the Oracle Database instance, and you are upgrading from Oracle Warehouse Builder 11g Release 1, then run the cat_owb_reposupgrade.sql script to upgrade it:

SQL> @C:\OWB112\owb\UnifiedRepos\cat_owb_reposupgrade.sql

7. Run the reset_owbcc_home.sql script to reset the OWB_HOME directory:

SQL> @C:/OWB112/owb/UnifiedRepos/reset_owbcc_home.sql

This entry is case-sensitive, does not accept a trailing slash, and requires forward slashes only, regardless of the operating system.

To prepare for an in-place repository upgrade on Linux

1. Ensure that you make a back-up copy of the OWBSYS schema, using the backup strategy employed in your organization.

2. At the command prompt, start SQL*Plus:

C:\> sqlplus

3. Connect as a user with administrative privileges:

SQL> connect sys as sysdba
Enter password: password

4. You have two options:

- If the OWBSYS schema does not exist on the Oracle Database instance, run the cat_owb.sql script:

SQL> @OWB112/owb/UnifiedRepos/cat_owb.sql

Enter the tablespace name when you are prompted for it.

- If the OWBSYS schema exists on the Oracle Database instance, and you are upgrading from Oracle Warehouse Builder 11g Release 1, then run the cat_owb_reposupgrade.sql script:

SQL> @OWB112/owb/UnifiedRepos/cat_owb_reposupgrade.sql

You are prompted for the tablespace name; enter it.

5. Run the reset_owbcc_home.sql script to reset the OWB_HOME directory:

SQL> @OWB112/owb/UnifiedRepos/reset_owbcc_home.sql

This entry is case-sensitive, does not accept a trailing slash, and requires forward slashes only, regardless of the operating system.

6. Unlock the OWBSYS and OWBSYS_AUDIT accounts, as described in the following sections:

- On Windows, "Unlocking the OWBSYS and OWBSYS_AUDIT Accounts"

- On Linux, "Unlocking the OWBSYS and OWBSYS_AUDIT Accounts"

Performing the In-Place Repository Upgrade

When upgrading from an Oracle Warehouse Builder 11g Release 1 repository, you are upgrading an existing OWBSYS schema on an existing repository. When upgrading from Oracle Warehouse Builder 10.2, your upgrade process creates a new workspace in the Oracle Warehouse Builder 11.2 repository, with the same name as the schema containing the Oracle Warehouse Builder 10.2 repository. In either case, the process is similar.

To perform an in-place repository upgrade

1. Start the Repository Assistant.

On Windows, from the Start menu, select Program Files, then Oracle - OWB112, then Warehouse Builder, then Administration, then Repository Assistant.

On Linux, from the command line, run OWB_HOME/owb/bin/unix/reposinst.sh.

2. On the Welcome page of the Repository Assistant, click Next.

3. On the Database Information page, enter the host name, port number, and service name where Oracle Warehouse Builder is installed.
Description of the illustration upgrade_00.gif

Click Next.

4. On the Choose Operation page, select Upgrade repository to current release of Oracle Warehouse Builder.
Description of the illustration upgrade_01.gif

Click Next.

5. On the Choose Upgrade Operations page, select Upgrade repository on the same database instance.
Description of the illustration upgrade_02.gif

Click Next.

6. On the OWBSYS Information page, enter the password for the OWBSYS user.
Description of the illustration upgrade_03.gif

Click Next.

7. The File Information page appears. The in-place repository upgrade process creates a repository export MDL file. The default file names and location for this exported MDL file and export log file are displayed here. You can change the location of these files.
Description of the illustration upgrade_04.gif

Click Next to accept the file information.

8. On the Summary page, click Finish to initiate the upgrade process.
Description of the illustration upgrade_05.gif

9. The Installation Progress popup window indicates the progress of the upgrade operation. When complete, click OK.

You may want to review the log for errors, and save the exported MDL file as a backup of your pre-upgrade repository.

Upgrading a Repository to Release 11.2 through MDL Files

You can upgrade an Oracle Warehouse Builder Release 10.2 or 11.1 Repository by exporting its content to a file, and then importing the file into an Oracle Warehouse Builder Release 11.2 Repository, using the Repository Assistant.

Exporting an Oracle Warehouse Builder Repository to a File

You export a repository with the Repository Assistant as follows.

To export a repository to a file

1. Start the Repository Assistant.
On Windows, from the Start menu, select Program Files, then Oracle - OWB112, then Warehouse Builder, then Administration, then Repository Assistant.

On Linux, from the command line, run OWB_HOME/owb/bin/unix/reposinst.sh.

2. On the Welcome page of the Repository Assistant, click Next.

3. On the Database Information page, enter the host name, port number, and the service name where Oracle Warehouse Builder is installed.

Click Next.

4. On the Choose Operation page, select Upgrade repository to current release of Oracle Warehouse Builder.
Description of the illustration upgrade_01.gif

Click Next.

5. On the Choose Upgrade Operation page, select Export entire repository to a file.
Description of the illustration export_01.gif

Click Next.

6. On the User Information page, for an Oracle Warehouse Builder Release 10.2 source, enter the user name and password of Oracle Warehouse Builder Release 10.2 repository owner. For an Oracle Warehouse Builder Release 11.1 source, enter the OWBSYS user name and password.
Description of the illustration export_02.gif

Click Next.

7. On the File Information page, enter the following information:

- File Name: the name of the MDL file for storing the repository.

- Log File: the name of the export operation log file that stores status and statistical information.

Description of the illustration upgrade_04.gif

Click Next.

8. On the Summary page, click Finish.
An Export Repository Progress window appears showing progress.

At the end of the export process, a status message appears. The export operation creates the file.

Importing a Repository Export MDL File to Oracle Warehouse Builder Release 11.2

To import a repository export MDL file

1. Start the Repository Assistant.
On Windows, from the Start menu, select Program Files, then Oracle - OWB112, then Warehouse Builder, then Administration, then Repository Assistant.

On Linux, from the command line, run OWB_HOME/owb/bin/unix/reposinst.sh.

2. On the Welcome page of the Repository Assistant, click Next.

3. On the Database Information page, enter the host name, port number, and the service name where Oracle Warehouse Builder Repository is installed. Click Next.

4. On the Choose Upgrade Operation page, select Import entire repository from file.
Description of the illustration import_02.gif

Click Next.

5. On the OWBSYS Information page, enter the OWBSYS password.
Description of the illustration import_01.gif

Click Next.

6. On the File Information page, enter or browse to find the name of the files used when exporting the repository.

Description of the illustration upgrade_04.gif

Click Next.

7. On the Summary page, click Finish.

Note:
When importing an Oracle Warehouse Builder Release 10.2 MDL repository export, the import process creates a workspace that has the same name as Oracle Warehouse Builder Release 10.2 repository schema. When importing an Oracle Warehouse Builder Release 11.1 repository export, the import process creates one workspace for each workspace being imported from Oracle Warehouse Builder Release 11.1 repository.

When importing an Oracle Warehouse Builder Release 10.2 MDL repository export, the import process creates a workspace that has the same name as the Oracle Warehouse Builder Release 10.2 repository schema. When importing an Oracle Warehouse Builder Release 11.1 repository export, the import process creates one workspace for each workspace being imported from Oracle Warehouse Builder Release 11.1 repository.

Deploying Any Process Flow Package With Repository Upgrade to Release 11.2

Oracle Warehouse Builder provides the utility to upgrade the entire repository from Release 10.2 to Release 11.2 through Repository Assistant. After the upgrade, you should use the Repository browser to update all locations, and then run the deployed objects, and mappings.

For Repository upgrade from Release 10.2 to Release 11.2, some extra steps are required for Process Flow, besides updating the locations through the Repository browser.

A warning information message is displayed after the location is upgraded.

Warning:
This OWF location has not been seeded.
It can be seeded by using the Design Client to deploy at least one Process Flow Package into it.

This warning message is not displayed every time, such as if you have both 11.2 and 10.2 Repositories, when you upgrade your Repository 10.2 to 11.2, you cannot see the warning as the packages are present in the Repository collectively.

Migrating the Repository to a Different Oracle Database Instance

The process of migrating the repository to a different Oracle Database instance involves the export of the existing repository to a file, and subsequent import of information from that file into a new repository on the other Oracle Database instance.

This process is virtually identical to upgrading from an Oracle Warehouse Builder Release 10.2 repository to a current version of the repository. The main differences are:

- Before the import, you must create users on the target instance with the same names as Oracle Warehouse Builder users on the original instance.

- At the time of importing, you must provide the credentials of a remote Oracle Database instance where the export files reside.

Note:
Check the latest Oracle Warehouse Builder Release Notes on http://www.oracle.com/technetwork/developer-tools/warehouse/overview/index.html before starting the migration process.

Exporting a Repository to MDL File

The export part of the scenario uses the Repository Assistant to create an MDL zip archive. This MDL zip archive includes information about all the workspaces in the repository, with each workspace stored as a separate file.

See Also:
"Exporting an Oracle Warehouse Builder Repository to a File" for a description of the export operation.

Creating Oracle Warehouse Builder Users in the Target Instance

Before importing the repository, in the target Oracle Database instance that contains the migrated repository, create the same users who had access to the original repository. You must do this to ensure that the security information is correctly imported. However, you must register these users as Oracle Warehouse Builder users; the upgrade process handles this automatically.

Importing a Repository from MDL File

"Importing a Repository Export MDL File to Oracle Warehouse Builder Release 11.2" describes the import operation. In step 6, you are entering the credential of the source (remote) database, which contains the repository MDL and log files.

Upgrading Locations to Oracle Warehouse Builder Release 11.2

The locations in your Oracle Warehouse Builder repository must also be upgraded for compatibility with Oracle Warehouse Builder 11.2 after the upgrade process. There are two ways to perform this upgrade:

- Use the script provided with Oracle Warehouse Builder Release 11.2.0.2 or higher. Oracle recommends using the provided scripts.
On Windows - run OWB_HOME\owb\bin\win32\upgradeloc.bat

On Linux - run OWB_HOME/owb/bin/unix/upgradeloc.sh

- Use the Repository Browser Locations Report to perform the upgrades one at a time. (This procedure is as effective as using the script, but requires more effort.)

Alternatively, you can also un-register and re-register all locations. However, in this case you must also redeploy all your mappings to affected locations; therefore, this procedure is not recommended.

Upgrading Locations to Oracle Warehouse Builder Release 11.2 Using the Repository Browser

You can also use Locations Reports from the Repository Browser to perform the locations upgrade process as follows.

To upgrade locations using the Repository Browser

1. In Repository Browser, select Control Center. Click Reports.

2. In the Reports window, under Deployment, click Locations Reports.
Description of the illustration locations_01.gif

3. On the Locations Report, under Logical Details, in the Validation column of the table, click Unknown.

Description of the illustration locations_02.gif

4. Under Connection details, under Location Status, because the status is Unknown, enter the password and click Get Status.
Description of the illustration locations_03.gif

The Current Status is Invalid.

5. Under Location Status, click Upgrade.

Description of the illustration locations_04.gif

The Current Status is now Valid.

6. Repeat steps 3 through 5 for all installations.

7. After you are finished, notice that the Validation column shows Tested locations
Description of the illustration locations_05.gif

Changes to Repository Objects When Moving to Oracle Warehouse Builder 11g Release 2

Design-time objects in your projects are automatically modified during the upgrade process to be compatible with Oracle Warehouse Builder Release 11.2. This section lists the changes that are made.

Changes to Oracle Warehouse Builder Release 10.2 and Release 11.1 Objects

When you move a design from Oracle Warehouse Builder Release 10.2 or Oracle Warehouse Builder Release 11.1 to Oracle Warehouse Builder Release 11.2, the following objects are modified during the migration or upgrade:

- Mapping Table Function Operators: The mapping operators for table functions are upgraded to have only one input group and one output group. Old input groups that were configured as a REF cursor type are upgraded to a SYS_REFCURSOR type, and a new construct operator is added to the map; its input group values are the same as in the REF cursor type input group, and the output group attribute is set to SYS_RECURSOR type.

- Mapping Key Lookup Operators: The mapping operators for key lookups are upgraded to the new lookup operator.

- Business Presentation Modules: Business presentation modules and their contents are discarded.

- BI Beans Locations: BI beans locations are discarded.

- Data Profile Metadata: Data profile metadata is not upgraded.

Changes to Oracle Warehouse Builder Release 9.2 and Release 10.1 Objects

When you move a design from Oracle Warehouse Builder Release 9.2 or Oracle Warehouse Builder Release 10.1 to Oracle Warehouse Builder Release 11.2, the following objects are modified during the migration or upgrade:

- Control Centers and Locations: After an upgrade, there is no association between the locations and the control centers that they reference. You must review the control center details using the Edit Control Center dialog box and select the locations associated with this control center.

- Locations and Control Center Connections: Locations and Control Center connections are moved out of the projects that own them so that they can be shared across the entire workspace. Thus the statistics in the import log file displays an additional project for these objects.

- Mapping Operator Names: The MDL Upgrade Utility ensures that the physical names and business names of all mapping operators are unique.

- Dimensions: An associated dimension table is created with the same name as the dimension. The table contains the columns, constraints, and attribute sets defined in the Dimension Editor Table Properties of the dimension in the earlier release.

- Cubes: An associated cube table is created with the same name as the cube. The cube table contains columns, constraints, and attribute sets defined in the Cube Editor Table Properties of the cube in the earlier release.

- Dimension and Cube Mapping Operators: The mapping operators for dimensions and cubes are converted to table operators. These table operators use the physical tables created by the MDL Upgrade Utility for dimensions and cubes.

- Mapping Display Sets for Dimension Hierarchies: Any mapping sets created based on the named attribute set for a dimension hierarchy are removed. This is because display sets for dimension hierarchies are no longer automatically created and maintained.

- Dimension Attributes: For each level attribute upgraded, a dimension attribute with the same name is created, if it does not exist in the dimension.

- Intelligence Objects and Reports: In the earlier release, intelligence objects and reports were available only using OMB Plus scripting. These objects are not upgraded.

- Advanced Queues: An associated queue table is created based on the property AQ queue table name. The queue table created by the MDL File Upgrade Utility contains a column whose data type is the object type for that advanced queue.

- Advanced Queue Operator in a Mapping: Mapping Advanced Queue operators are changed to contain only one attribute called PAYLOAD. For Mapping Advanced Queue operators that are used as a source, a new Expand operator is added after the Mapping Advanced Queue operator. For Mapping Advanced Queue operators that are used as a target, a new Construct operator is added before the Mapping Advanced Queue operator.

7 Configuring Repository Browser, Control Center Agent, and Other Components

This section describes how to configure the Repository Browser environment within Oracle Warehouse Builder, and Control Center Agent for Oracle Application Server. Procedures for installing optional components are also described.

This section includes the following topics:

- "Configuring the Repository Browser Environment"

- "Configuring Control Center Agent for Oracle Application Server"

- "Integrating with E-Business Suite"

- "Installing Third-Party Name and Address Data"

- "Integrating with Oracle Workflow"

Configuring the Repository Browser Environment

The Repository Browser connects to Oracle Warehouse Builder repositories and enables you to view metadata, run Web reports, perform lineage and impact analysis on your metadata, and audit run-time executions.

When you install Oracle Warehouse Builder from Oracle Universal Installer, the Repository Browser is also installed and runs in all the languages that you selected during installation.

To verify the installation, start the Repository Browser listener and then the Repository Browser. For information on how to use the Repository Browser, refer to Oracle Warehouse Builder Data Modeling, ETL, and Data Quality Guide.

Changing the Session Timeout

By default, Repository Browser sessions time out after one hour of inactivity. To change, edit the web.xml file located at OWB_HOME\owb\j2ee\applications\owbb\WEB-INF by updating the session-config tag.

By default, the tag displays as follows:

<session-config>
<session-timeout>60</session-timeout>
</session-config>

Configuring Control Center Agent for Oracle Application Server

The procedures in this section describe how to install and configure Control Center Agent to run in Oracle Application Server. This section includes the following topics:

- "Modifying the OC4J Startup Script"

- "Configuring Control Center Agent Server-side Logging"

- "Configuring the Audit Data Source"

- "Setting Control Center Agent Security Roles"

- "Creating JMS Queues"

- "Setting the PATH Environment Variable"

- "Deploying the Control Center Agent to OC4J"

- "Configuring the Control Center Agent Web Service (jrt-web.war)"

- "Enabling Control Center Agent Audit Table Logging"

- "Installing JDBC Drivers for OC4J"

- "Overview of Control Center Agent Files"

- "Installing Code Templates for Use from Control Center Agent"

Modifying the OC4J Startup Script

This section describes how to modify the OC4J startup script.

To modify the OC4J startup script:

1. Ensure that you are in the application server configuration directory, AS_HOME/opmn/config. AS_HOME stands for the root home directory of the application server.

2. Open the file opmn.xml in a text editor.

3. Alter the contents of the file as demonstrated in the following example, where bold font indicates the edits you must make.

- Setting MaxPermSize parameter at 128M allocates enough PermGen space to OC4J to run the Control Center Agent.

- The Python.path sets the path for the Python library files used by the Control Center Agent: jython_lib.zip and jython_owblib.jar. These two files are in the OWB_HOME/owb/lib/int directory.

- The km_security_needed property determines if restrictions are applied to the types of operating system commands enabled by Oracle Warehouse Builder Code Template script that runs in the Control Center Agent. Setting it to true enforces restrictions.
To review the list of commands allowed by this security mechanism, check the file AS_HOME/j2ee/home/config/ct_permissions.properties (it can be specified in the jrt.xml configuration file), which is available after Control Center Agent successfully installs in the OC4J in Application Server.

<ias-component id="default_group">
<process-type id="home" module-id="OC4J" status="enabled">
<module-data>
<category id="start-parameters">
<data id="java-options" value="-server
-XX:MaxPermSize=128M
-ms512M -mx1024M
-XX:AppendRatio=3
-Dpython.path=/home/lib/jython_lib.zip:/home/lib/jython_owblib.jar
-Dkm_security_needed=true
...
</ias-component>

Configuring Control Center Agent Server-side Logging

To set up the Control Center Agent server-side logging:

1. Ensure that you are in the OC4J server configuration directory, OC4J_HOME/j2ee/home/config/. OC4J_HOME stands for the root home directory of the OC4J.

2. Open the file j2ee-logging.xml in a text editor.

3. Alter the contents of the file as demonstrated in the following example, where bold font indicates the edits you must make.

- In the log handler section, the jrt-internal-log-handler is the handler used by Control Center Agent run-time logger to create log files.

- In the logger section, you are creating the logger for Control Center Agent run-time auditing.

<!-- The log handler used by JRT run-time logger -->
<log_handler name="jrt-internal-log-handler"   class="oracle.core.ojdl.logging.ODLHandlerFactory">
<property name="path" value="../log"/>
<property name="maxFileSize" value="10485760"/>
<property name="maxLogSize" value="104857600"/>
<property name="encoding" value="UTF-8"/>
</log_handler>
...
<!-- The JRT run-time logger for run-time auditing -->
<logger name="oracle.wh.jrt.server.audit" level="ALL"
useParentHandlers="false">
<handler name="jrt-internal-log-handler"/>
</logger>

Configuring the Audit Data Source

To configure the audit data source:

1. Ensure that you are in the OC4J server configuration directory, OC4J_HOME/j2ee/home/config/. OC4J_HOME stands for the root home directory of the OC4J.

2. Open the file data-sources.xml in a text editor.

3. Define the audit data source as demonstrated in the following example, where bold font indicates the edits you must make.

<managed-data-source name="AuditDS" connection-pool-name="OWBSYS Audit
Connection Pool" jndi-name="jdbc/AuditDS"/>
<connection-pool name="Oracle Audit Connection Pool">
<connection-factory factory-class="oracle.jdbc.pool.OracleDataSource"
user="username" password="password"
url="jdbc:oracle:thin:@//localhost:1521/ORCL"/>
</connection-pool>

Setting Control Center Agent Security Roles

To configure Control Center Agent security roles:

1. In a Web browser, navigate to the Enterprise Manager home page.

2. Log in using the oc4jadmin credentials. You may be prompted to activate the oc4jadmin account. If prompted to activate the account:
Create a password for the oc4jadmin account to activate it. Enter the password you want to use. Confirm the password and click OK to activate the account.

3. On the Cluster Topology page, locate the link to the OC4J instance installed under the Application Server.
Description of the illustration jrt_security_01.gif

4. Click home (the OC4J instance).
This takes you to the home page of the OC4J instance.

5. On the OC4J home screen, click the Administration tab.
Description of the illustration jrt_security_02.gif

6. On the Administration Tasks screen, expand Security.

7. Click the task icon next to Security Providers.
Description of the illustration jrt_security_03.gif

8. On Security Providers screen, click Instance Level Security.
Description of the illustration jrt_security_04.gif

9. On Instance Level Security screen, click the Realms tab.
Description of the illustration jrt_security_05.gif

10. Under the Realms tab, in the default realm jazn.com, click the number in Roles column.
Description of the illustration jrt_security_06.gif

11. On the Roles screen, click Create.
Description of the illustration jrt_security_07.gif

12. On the Add Role screen, enter Name OWB_J2EE_EXECUTOR.
Click OK.

Description of the illustration jrt_security_08.gif

13. On the Add Role screen, enter Name OWB_J2EE_OPERATOR.
Click OK.

Description of the illustration jrt_security_08.gif

14. On the Add Role screen, enter Name OWB_J2EE_OPERATOR.
Under Assign Roles, in the list of Available Roles, select OWB_J2EE_EXECUTOR and oc4j-administrators, and move to the list of Selected Roles.

Click OK.

Description of the illustration jrt_security_09.gif

15. On the Add Role screen, enter Name OWB_J2EE_ADMINISTRATOR.
Under Assign Roles, in the list of Available Roles, select OWB_J2EE_OPERATOR and OWB_J2EE_EXECUTOR, and move to the list of Selected Roles.

Click OK.

Description of the illustration jrt_security_10.gif

16. On the breadcrumb, click Instance Level Security.

17. Under the Realms tab, in the default realm jazn.com, click the number in Users column.

18. On the Users screen, click user oc4jadmin.
Description of the illustration jrt_security_11.gif

19. Under Assign Roles, in the list of Available Roles, select OWB_J2EE_ADMINISTRATOR and oc4j_app_administrators, and move to the list of Selected Roles.
Click Apply.

20. On the breadcrumb, click Instance Level Security.

21. Under the Realms tab, in the default realm jazn.com, click the number in Roles column.

22. Click Create.

23. On the Add Role screen, enter Name OWB_INTERNAL_USERS.
Click OK.

Creating JMS Queues

You must create two JMS queues, for JRT:owbQueue, and for JRT:owb_abortQueue.

To create JMS Queues:

1. On the breadcrumb, click OC4J:home.

2. On the OC4J:home screen, click the Administration tab.

3. Expand Services, and then expand Enterprise Messaging Service.
Description of the illustration jms_queues_01.gif

4. Click the task icon next to JMS Destinations.

5. On JMS Destinations screen, click Create New.
Description of the illustration jms_queues_02.gif

6. On Add Destination screen, choose Destination Type Queue, enter Destination Name owbQueue, select Persistence In Memory Persistence Only, and enter JNDI Location jms/owbQueue.
Click OK.

Description of the illustration jms_queues_03.gif

7. On Add Destination screen, choose Destination Type Queue, enter Destination Name owb_abortQueue, select Persistence In Memory Persistence Only, and enter JNDI Location jms/owb_abortQueue.
Click OK.

Setting the PATH Environment Variable

To ensure that system commands such as linux ls, sh, and so on, can run normally in scripts within the Control Center Agent, the environment variable PATH must be hold the directory that contains the system commands.

To set the PATH environment variable:

1. On the breadcrumb, click OC4J:home.

2. On the OC4J:home screen, click the Administration tab.

3. Expand Administration Tasks, then expand Properties.
Description of the illustration jrt_path_01.gif

4. Click the task icon next to Server Properties.

5. On the Server Properties screen, scroll downwards to Environment Variables section.

6. Under Environment Variables, click Add Another Row.

7. Enter PATH in Name, and fill Value with directories that contain the system commands.
Click Apply.

Description of the illustration jrt_path_02.gif

Deploying the Control Center Agent to OC4J

To deploy the Control Center Agent to OC4J:

1. On the breadcrumb, click OC4J:home.

2. On the OC4J:home screen, click the Applications tab.

3. Click Deploy to begin deploying Control Center Agent.
Description of the illustration deploy_01.gif

4. On the Deploy: Select Archive screen, under Archive, select Archive is present on local host. Upload the archive to the server where Application Server Control is running.
Click Browse and locate the jrt.ear file in the OWB_HOME/owb/jrt/applications directory.

Description of the illustration deploy_02.gif

5. Under Deployment Plan, select Automatically create a new deployment plan.
Click Next.

While the upload is in progress, you see the Deploy: Uploading screen.

Description of the illustration deploy_03.gif

6. On the Deploy: Application Attributes screen, enter Application Name jrt, and Context Root jrt. Leave the other attributes at their default values.
Click Next.

Description of the illustration deploy_04.gif

7. On Deploy: Deployment Settings screen, leave all attributes at their default values, and click Deploy.
Description of the illustration deploy_05.gif

8. After the application is successfully deployed, a confirmation message displays.
Description of the illustration deploy_06.gif

9. On the Confirmation screen, click Return.
Under the Applications tab, expand All Applications, then expand default.

The new application CCA is up.

Configuring the Control Center Agent Web Service (jrt-web.war)

The Control Center Agent Web Service is deployed automatically with Control Center Agent. No additional setup is required.

To check that the Web Service is running:

1. On the breadcrumb, click OC4J:home.

2. On the OC4J:home screen, click the Web Services tab.
JRTWebService is listed.

Description of the illustration jrt_web_services_01.gif

To test the Web Service:

1. Under the Web Services tab, select JRTWebService and click Test Service.

2. On the Test Web Service: HttpSoap11 screen, under Discovered Web sites, select the http site and click Test Web Service.
Description of the illustration jrt_web_services_02.gif

3. The JRTWebService endpoint screen displays that the Web Service is running.
You can access the operations available from the Operation drop down box, fill in the required parameters, and then click Invoke to execute the operation.

Description of the illustration jrt_web_services_03.gif

4. [Optional] Alternatively, go to http://AS_hostname/jrt/webservice.

To use the Web Service with a secure Web site (available only to admin users):

1. Create or modify the secure-web-site.xml file in the config directory.

2. A sample secure-web-site.xml file is listed below.
The relevant code is in bold typeface.

Particularly, ensure that protocol is set to https, secure is set to true, and a secure http port is identified. Additionally, you must create a keystore file and add the ssl-config entry (you must use an absolute path for the key store file).

<?xml version="1.0" standalone="yes"?>

<web-site
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation=
"http://xmlns.oracle.com/oracleas/schema/web-site-10_0.xsd"
display-name="OC4J 10g (10.1.3) Secure Web Service"
schema-major-version="10"
schema-minor-version="0"
protocol="https"
port="4443"
secure="true"
>
<ssl-config keystore="directory_path/owb/jrtrun/config/serverkeystore.jks"
keystore-password="password"/>

<default_web_app application="default" name="defaultWebApp" />
<web-app application="system" name="dms0" root="/dmsoc4j" access-log="false"
load-on-startup="true" />
<web-app application="system" name="dms0" root="/dms0" access-log="false"
load-on-startup="true" />
<web-app application="system" name="JMXSoapAdapter-web"     root="/JMXSoapAdapter" />
<web-app application="default" name="jmsrouter_web" root="/jmsrouter"
load-on-startup="true" />
<web-app application="javasso" name="javasso-web" root="/jsso"
load-on-startup="false" />
<web-app application="ascontrol" name="ascontrol" root="/em"
load-on-startup="true" ohs-routing="false"/>
<web-app application="jrt" name="jrtws" load-on-startup="true" root="/jrt" />

<!-- Access Log, where requests are logged to -->
<access-log path="../log/secure-web-access.log"
split="day" />

<!- Uncomment this to use ODL logging capabilities
<odl-access-log path="../log/secure-web-access" max-file-size="1000"
max-directory-size="10000" />
-->

</web-site>

3. After you create the secure-web-site.xml file, deploy it to jrtws.war, you may access the JRTWebService securely through https://hostname:4443/jrt/webservice.

Enabling Control Center Agent Audit Table Logging

To enable Audit Table logging, you must set up a connection pool, and then a managed data source before Control Center Agent deployment.

Configuring OWBSYS Audit Connection Pool

To configure the OWBSYS Audit Connection Pool:

1. On the breadcrumb, click OC4J:home.

2. On the OC4J:home screen, click the Administration tab.

3. Expand Services.
Description of the illustration audit_conn_pool_01.gif

4. Click the task icon next to JDBC Resources.

5. On the JDBC Resources screen, under Connection Pools, click Create.
Description of the illustration audit_table_02.gif

6. On the Create Connection Pool - Application screen, under Application, select default.
Under Connection Pool Type, select New Connection Pool.

Click Continue.

Description of the illustration audit_conn_pool_02.gif

7. On the Create Connection Pool screen, enter the Name OWBSYS Audit Connection Pool. Under URL, select JDBC URL, and enter the URL (in this example, jdbc:oracle:thin:@localhost:1521:ora111 is used for a local installation).
Under the Credential section, enter the User Name (in this example, owbsys_audit), and enter the Use Cleartext Password.

Description of the illustration audit_conn_pool_03.gif

8. [Optional] On the Confirmation screen, test the availability of the connection. Click Test Connection.
Description of the illustration audit_conn_pool_04.gif

9. On the Test Connection: "OWBSYS Audit Connection Pool" screen, click Test.
Description of the illustration audit_conn_pool_05.gif

A confirmation screen appears.

Note:
Application Server 10g is not case-sensitive when verifying Oracle Database credentials; it converts all letters to lowercase before attempting to connect to the database. Because Oracle Database Release 11g Release 1 and subsequent releases are case sensitive, create user credentials in lowercase when using for Audit Table logging to prevent the Invalid username/password error message.

Configuring an Audit Table Data Source

To deploy Control Center Agent to OC4J, you must also configure the data source for the audit table. This data source is required by Control Center Agent; if not configured, the Control Center Agent deployment fails.

To configure the audit table data source:

1. On the breadcrumb, click OC4J:home.

2. On the OC4J:home screen, click the Administration tab.

3. Expand Services.
Description of the illustration audit_table_01.gif

4. Click the task icon next to JDBC Resources.

5. On the JDBC Resources screen, under Data Sources, click Create.
Description of the illustration audit_table_02.gif

6. On the Create Data Source - Application & Type screen:

- Under Application, select Application default.

- Under Data Source Type, select Managed Data Source.

- Click Continue.

Description of the illustration audit_table_03.gif

7. On the Create Data Source - Managed Data Source screen,

- Enter Name AuditDS.

- Enter JNDI Location jdbc/AuditDS.

- Click Finish.

If you do not require audit table logging, leave other parameters at their default values.

Description of the illustration audit_table_04.gif

Installing JDBC Drivers for OC4J

The following instructions demonstrate how to install JDBC drivers for OC4J.

To install the JDBC drivers for OC4J:

1. Obtain the *.jar file that contains the JDBC driver for your desired platform.

2. Stop the OC4J service.

3. Copy the JDBC driver file into the AS_HOME/j2ee/home/applib directory, where AS_HOME is the Application Server home.

4. Restart the OC4J service.

Overview of Control Center Agent Files

This section describes the files generated at run time. If you application name is other than jrt, it appears in these directory paths as app_name.

The Control Center Agent files include:

- "ODL Job Log Files"

- "Control Center Agent Run-Time Log File"

- "JobID File"

- "Control Center Agent Settings"

- "JRTAdministratorMBean"

ODL Job Log Files

By default, ODL Job log files are located in the AS_HOME/j2ee/home/log/app_name directory.

Each job log resides in its own directory. For example, log file for job 10 is in AS_HOME/j2ee/home/log/app_name/job10/log.xml, and the metadata file for job 10 in AS_HOME/j2ee/home/log/app_name/job10/meta_data.txt.

You may choose to configure Control Center Agent to store the log files in other directories; ensure that Control Center Agent can access these log directories.

Control Center Agent Run-Time Log File

The Control Center Agent run-time log file app_name.log employs the ODL log file rotation mechanism. The current run-time log is always app_name.log, while older log files are app_name.log.N, where N is the round of log rotation). By default, this file is:

AS_HOME/j2ee/home/log/app_name.log

JobID File

Control Center Agent uses a file to keep track of the current job ID in the system; be careful not to remove this file. This file can be in one of two possible locations:

- When the Control Center Agent is installed as part of the larger Oracle Warehouse Builder installation, the file is at:

OWB_HOME/owb/jrt/application-deployments/jrt/counter/counter.info

- When the Control Center Agent is installed on the Application Server, the file is at:

AS_HOME/j2ee/home/applications/application_name/counter/counter.info

Control Center Agent Settings

Control Center Agent settings are persisted in the file jrt.xml. You may modify the settings in this file directly, and then restart Control Center Agent. Alternatively, you can modify these settings by changing the attributes of the "JRTAdministratorMBean" in Enterprise Manager. This file is:

AS_HOME/j2ee/home/applications/app_name/config/jrt.xml

JRTAdministratorMBean

The JRTAdministratorMBean enables you to dynamically change Control Center Agent settings without restarting the Control Center Agent.

To change Control Center Agent settings with the JRTAdministratorMBean

1. On the breadcrumb, click OC4J:home.

2. On the OC4J:home screen, click the Applications tab.

3. Expand All Applications, then expand default.

4. In the jrt row, click the task icon in column Application Defined MBeans.
Description of the illustration admin_bean_01.gif

5. On the Application MBeans screen, in the left-hand side navigation menu, select JRTAdministrator.
The right-hand side shows all the Attributes and Operations of JRTAdministrator MBean, under the corresponding tabs.

Description of the illustration admin_bean_02.gif

6. Change the attributes to desired values, then click Apply.

Installing Code Templates for Use from Control Center Agent

To use a code template, you must install any additional JDBC driver files that it requires to access heterogeneous systems on all the client computers and on the computer that hosts the Control Center Agent.

To install a Code Template:

1. Load the required JDBC drivers to the OWB_HOME/owb/lib/ext directory.

2. Import the code templates into any projects that uses them, in the design client.
Import the code template for the project. After it is imported, all users working on the project can use the code template.

Integrating with E-Business Suite

When integrating with Oracle E-Business Suite (EBS), you must first import its metadata, and then design mappings for moving and transforming data. Specifically:

- During the design phase, Oracle Warehouse Builder users must have access to metadata in the APPS schema.

- During the execution phase, Oracle Warehouse Builder users must access the data in the APPS schema.

Because direct access to the APPS production schema may be limited and restricted, you may define a user on the EBS database for Oracle Warehouse Builder users to access only the relevant metadata and data.

To enable access to EBS data and metadata:

1. Create a user on the database that hosts the EBS. This user needs, at minimum, CONNECT and RESOURCE privileges.

2. Grant access to the relevant metadata by running the OWB_HOME\owb\cmi\ebs\owbebs.sql script.
This script grants access to the following tables in the APPS schema, which contain metadata for EBS tables, views, sequences, and keys:

- FND_APPLICATION

- FND_APPLICATION_VL

- FND_TABLES

- FND_VIEWS

- FND_SEQUENCES

- FND_COLUMNS

- FND_PRIMARY_KEYS

- FND_FOREIGN_KEYS

- FND_PRIMARY_KEY_COLUMNS

- FND_FOREIGN_KEY_COLUMNS

The script also creates a synonym in the user schema for each of the preceding objects.

3. Enable a user to extract data from the EBS database.
You can create a new user, or grant the appropriate privileges to the same user you created earlier. For each object from which you want to enable data extraction, grant this user at least SELECT access.

Oracle Warehouse Builder users can now import the E-Business Suite metadata as described in the importing section of Oracle Warehouse Builder Data Modeling, ETL, and Data Quality Guide.

Installing Third-Party Name and Address Data

Oracle Warehouse Builder gives you the option to perform name and address cleansing on your data with the Name and Address operator. The Name and Address operator identifies and corrects errors and inconsistencies in name and address source data. The operator identifies inconsistencies by comparing input data to data libraries supplied by the third-party name and address cleansing software vendors. Purchase the data libraries directly from these vendors.

To install data libraries, refer to the installation instructions of the name and address cleansing software vendor of your choice. For the list of certified name and address cleansing software providers, refer to Oracle Technology Network at http://www.oracle.com/technetwork/developer-tools/warehouse/overview/index.html.

To integrate with third-party name and address data libraries:

1. Install Oracle Warehouse Builder as instructed in this guide.

2. Purchase data libraries from certified vendors listed on My Oracle Support at https://support.oracle.com.

3. Install and access the certified vendor's data libraries and Name and Address adapter following the vendor's instructions.
If you are installing in an Oracle Real Application Cluster environment, then you may be able to install the name and address adapter on many nodes to benefit from the parallelism and failover enabled by Oracle RAC architecture. Check with your vendor to see if your purchase license allows a multiple-node installation.

You are not required to install the data libraries on multiple nodes. However, if you install all data libraries on one node, then performance may suffer due to file access time latency. Follow the recommendations of your name and address cleansing software vendor.

4. Design a mapping using the Name and Address operator to cleanse name or address data. Refer to Oracle Warehouse Builder Data Modeling, ETL, and Data Quality Guide for information on designing mappings using the Name and Address operator.

Integrating with Oracle Workflow

If you plan to use Oracle Warehouse Builder process flows, then use Oracle Workflow to enable deployment as described in this section.

See Also:
Oracle Warehouse Builder Data Modeling, ETL, and Data Quality Guide for more information about schedules.

To enable integration with Oracle Workflow:

1. Stop all running OC4J instances.

2. Locate Oracle Workflow installation program, at OWB_HOME\owb\wf\install\wfinstall.*.
If you installed Oracle Warehouse Builder 11g on Oracle Database 10g Release 2, separately download the software for Oracle Workflow 2.6.4.

3. Start Oracle Workflow installation program.
On Windows, enter the following at the command prompt:

C:\>  cd OWB112\owb\wf\install
C:\OWB112\owb\wf\install> wfinstall.bat

On Linux, enter the following in the shell:

% cd OWB112/owb/wf/install
% wfinstall.csh

If you use multiple Oracle databases, you must unset the environment variables related to Oracle, such as ORACLE_HOME, ORACLE_SID, ORACLE_PORT, and LD_LIBRARY_PATH.

4. Complete the Workflow Configuration Assistant using following values:

- Install Option: Server Only

- Workflow Account: owf_mgr

- Workflow Password: wf_password

- SYS Password: sys_password; use the SYS password for the database where installing Oracle Workflow.

- TNS Connect Descriptor: hostname:port:service_name, where the values correspond to your database.
Because the assistant does not reference the tnsnames.ora file, do not use a net service name.

- LDAP Parameters: this is optional; see Oracle Workflow documentation for details.

- Mailer Parameters: this is optional; see Oracle Workflow documentation for details.

- Tablespace: this is optional; you may change the tablespace.

5. Click Submit to start the Workflow configuration process.
The configuration process can take several minutes. Check OWB112/owb/wf/install/wf.log for messages to follow the progress of the configuration process.

When the process is complete, the Workflow Configuration Assistant displays a message of completion.

6. Install the Workflow Client [Optional].
The installation of Oracle Workflow client is optional because the Process Flow Editor in Oracle Warehouse Builder replaces its functionality. You may want to install Oracle Workflow client to view the deployed Oracle Warehouse Builder processes in Oracle Workflow.

On the computer that hosts Oracle Warehouse Builder client, install Oracle Workflow client from Oracle Workflow client CD.

7. Create a Workflow Proxy User.
When the Workflow instance is not on the same computer that hosts Oracle Warehouse Builder repository, you must create a proxy user.

Within the database hosting the repository, use SQL Plus to create a user and grant it the OWB_USER role as a default. It enables the remote Oracle Workflow instance to connect to the services provided by the Control Center.

Considerations for the OWB_USER Role

If you encounter a problem when trying to grant the OWB_USER role, then possibly OWB_USER exists in an earlier Oracle Warehouse Builder implementation. In this case, you must first rename the existing OWB_USER to something else before you can grant a user the OWB_USER role in the current release. In order to retain the properties for the renamed role, you must register it in the new installation of Release 11.2.

Part II

Administering Oracle Warehouse Builder

This part contains the following sections:

- Chapter 8, "Managing Configurations"

- Chapter 9, "Managing the Control Center and Repository"

- Chapter 10, "Managing the Control Center Agent"

- Chapter 11, "Using Snapshots to Manage Metadata"

- Chapter 12, "Importing, Exporting, and Upgrading Metadata"

- Chapter 13, "Managing Security"

8 Managing Configurations

This section describes the design issues associated with multiple configuration environments.

This section includes the following topics:

- "About Configuration Management"

- "Creating Configurations Templates"

- "Editing Configuration Templates"

- "Activating Configurations"

- "Configuring Objects"

About Configuration Management

When you install Oracle Warehouse Builder and create a new repository, you have a default project with a single automatic default configuration, DEFAULT_CONFIGURATION. See Figure 8-1 and note that each new project has an automatic DEFAULT_CONFIGURATION. You can observe this by expanding the Configurations node in Project Navigator. Note also that the active configuration appears on the toolbar as DEFAULT_CONFIGURATION.

This default configuration contains the default physical properties of all the data objects in the project; these properties are necessary for deployment. As a single entity, the DEFAULT_CONFIGURATION enables deployment to the default control center, DEFAULT_CONTROL_CENTER, and default agent, DEFAULT_AGENT, which are necessary to the internal workings of Oracle Warehouse Builder.

When you define a new configuration, Oracle Warehouse Builder adds it to the list of configurations. With multiple configurations, you can specify how the same logical object may be defined across various environments: you can define multiple physical properties and deployment details for a single table, view, or other such object. In this manner, configurations enable you to connect design objects to their realizations.

If you link a configuration to a template, the configuration picks up the default values of the configuration properties from this template; enabling you to override the existing set of configuration values with your own values.

Configurations have several roles in Oracle Warehouse Builder environment:

- The key role of a configuration is to determine which Control Center Service and Control Center Agent manage the deployment and the deployment location. A configuration is always associated with only one Control Center and CCA, and specifies which of the services controls the deployment of any objects when this configuration is active. The configuration settings of the design objects control the Location property. For example, each Oracle Database module has a configuration property Location; the value of the Location property must be a reference to an Oracle Database location, and it determines where any objects inside the module are deployed.

- The other role of configurations is to capture information specific to the creation and use of an object for a specific location. For example, you can define the tablespace where a new table should be created.

Figure 8-1 Oracle Warehouse Builder Configuration Management

Description of "Figure 8-1 Oracle Warehouse Builder Configuration Management "

Configuration details are grouped by type, such as performance parameters, storage space for tables, and so on. Because each object type can have several configuration properties that are not used or have general defaults, Oracle Warehouse Builder uses Configuration Templates to simplify how much the user must do.

Configuration Templates may be used to override automatic default values for configuration properties and to flag the properties for either the general set or the advanced set. For example, one may move the less frequently used configuration properties to the advanced set.

Creating Configurations Templates

To create a configuration template:

1. In the Globals Navigator, select Configuration Templates.

2. Right-click Configuration Templates, and select New Configuration Template.
Description of the illustration new_config_temp_01.gif

The Create Configuration Template wizard opens. On every screen of the wizard, you have the option of clicking Help to get more information.

3. On the Name and Description screen, enter the Name of the new configuration template, and optionally, its Description.
Click OK.

Description of the illustration new_config_temp_02.gif

4. The new Configuration Template appears in the right pane of Oracle Warehouse Builder console.
When you create a new configuration template, its default setting of advanced options is initially set to be identical to previously created configuration templates.

Description of the illustration new_config_temp_03.gif

Editing Configuration Templates

To edit the configuration values in a template, use the Configuration Template Editor, that enables to set the configuration properties of objects to Advanced, and to override the existing configuration defaults.

The configuration template editor can show the different templates side by side, to help compare and edit multiple templates.

To edit a configuration template:

1. In the Globals Navigator, under Configuration Templates, click the Manage Configuration Template Columns icon.
Description of the illustration edit_config_temp_01.gif

2. In the Select Templates window, select the templates you want to edit.
Click OK.

Description of the illustration edit_config_temp_02.gif

3. Click the Expand All icon.
Description of the illustration edit_config_temp_03.gif

4. Make changes to the side-by-side templates.
Description of the illustration edit_config_temp_04.gif

Activating Configurations

To activate a configuration:

1. In the Project Navigator, select a project and expand its navigation tree.

2. Expand the Configurations folder.

3. Select a configuration.

4. Right-click the selected configuration; from the menu, select Set As Active Configuration.
Description of the illustration set_config_01.gif

All changes that you make to the configuration parameters of objects are saved in this configuration. If you switch to the previous configuration, these parameters show the settings of that configuration.

The Control Center service and Control Center Agent associated with this configuration are now set; they manage all future deployments or executions.

Configuring Objects

When you choose the Configure option for any object, it shows the set of configuration properties with the default values that are defined in the Configuration Template. You can expand the Property tree to see all properties.

Configuration defines the physical characteristics of data objects. These may include defining a tablespace and setting performance parameters in the configuration of a table.

You may change the configuration of an object at any time before deployment, and that it is possible to define multiple configurations for the same set of objects. This is particularly useful when deploying to multiple environments, such as test and production.

All objects have a parameter deployable, which is selected by default. To prevent an object from being deployed, deselect this parameter.

To configure an object:

1. In the Project Navigator, select the object to configure.

2. In the File menu, click Configure.

Description of the illustration configuration_01.gif

The Configuration editor is displayed.

3. Select a parameter to display and edit its value in the right-side panel.
Description of the illustration configuration_02.gif

4. Click Help for additional information.

9 Managing the Control Center and Repository

Users must manage Oracle Warehouse Builder Control Center service and repository. You can use the utilities in the OWB_HOME/owb/rtp/sql directory by accessing them at the command prompt. This section describes the available resources and tools, and the necessary management tasks.

This section contains the following topics:

- "Overview of Oracle Warehouse Builder Control Center and Repository Management"

- "Oracle Warehouse Builder Administrative Utilities"

- "Overview of Oracle Warehouse Builder Repository Browser"

Overview of Oracle Warehouse Builder Control Center and Repository Management

Oracle Warehouse Builder Control Center, Control Center service, and Oracle Warehouse Builder repository occasionally require administration tasks that go beyond Oracle Warehouse Builder Control Center Manager GUI.

These tasks can be divided into the following groups:

- "Starting and Stopping the Control Center Service"

- "Displaying and Managing Control Center Configuration"

- "Managing Control Center Deployment and Execution Jobs"

- "Oracle Warehouse Builder Repository and Location Administration Utilities"

Details about each group of tasks and the associated commands are provided in the following sections.

See also:

- An architectural overview including each of the major Oracle Warehouse Builder architectural components in Oracle Warehouse Builder Concepts

- Process of submitting deployment and execution requests to the Control Center Service in Oracle Warehouse Builder Concepts

- Deployment and execution jobs in Oracle Warehouse Builder Concepts

- Commands used for managing the Control Center Agent, described in Chapter 10, "Managing the Control Center Agent"

- Runtime Preferences in Oracle Warehouse Builder Concepts

Starting and Stopping the Control Center Service

A group of commands starts and stops the control center service, displays its current availability, and troubleshoots a range of issues.

This group includes the following commands:

- "service_doctor" displays a variety of Oracle Warehouse Builder repository and Control Center service diagnostics.

- "show_service" displays the status of the Control Center service as either Available or Not Available.

- "start_service" starts a Control Center service.

- "stop_service" stops a Control Center service.

Displaying and Managing Control Center Configuration

Another group of commands displays and modifies the properties of the Control Center, thereby modifying its behavior.

This group includes the following commands:

- "display_platform_property" displays the value of a platform property.

- "set_ccs_home" sets the properties associated with a Control Center Service.

- "set_platform_property" sets the value of a platform property.

- "set_platform_property_from_file" sets the value of a platform property from a specified file location.

Managing Control Center Deployment and Execution Jobs

The third group of commands overrides default handling of an Oracle Warehouse Builder deployment or execution requests by the Control Center, deactivates or aborts a job, or expedites handling of a specific request.

This group includes the following commands:

- "abort_exec_request" terminates a run that is currently busy.

- "abort_unit_request" terminates a deployment job at the unit level.

- "deactivate_all" deactivates all incomplete deployment and execution jobs.

- "deactivate_deployment" deactivates a deployment job.

- "deactivate_execution" deactivates an execution job.

- "expedite_exec_request" expedites a running job.

- "list_requests" lists the details of any active deployment or execution requests.

- "print_exec_details" prints the audit execution hierarchy and details about executions to a text file.

- "print_running_exec_details" prints the audit execution hierarchy and details about the incomplete executions to a text file.

- "sqlplus_exec_background_template" runs the specified object in the background, as a nonblocking call.

- "sqlplus_exec_template" runs the specified object as a blocking call.

Oracle Warehouse Builder Repository and Location Administration Utilities

Oracle Warehouse Builder repository and locations sometimes require direct manipulation. Also, run-time audit data accumulates in Oracle Warehouse Builder repository, and some users may want to purge historical run-time audit data, to improve performance.

This fourth group includes the following commands:

- "delete_warehouse_object" deletes a warehouse object from a location in the repository.

- "grant_error_table_privileges" enables the Repository Browser to view and purge error tables.

- "grant_upgrade_privileges" grants the required roles and privileges for upgrade deployment actions to a specific user.

- "UpdateControlCenter" sets the host, port, and service parameters for the Control Center in Oracle Warehouse Builder Client Repository.

- "UpdateLocation" sets the host, port, and service parameters for the location in Oracle Warehouse Builder Client Repository.

- "purge_audit_template" purges either deployment or execution audit data..

- "reset_repository" resets the registration details of an Oracle Warehouse Builder repository.

- "rtrepos_report" displays the details of the Control Center and its registered locations.

- "set_repository_password" sets the password for Oracle Warehouse Builder.

Oracle Warehouse Builder Administrative Utilities

The following information is an alphabetical list of Oracle Warehouse Builder administrative utilities.

abort_exec_request

The abort_exec_request.sql script terminates a run that is currently busy.

Connect as workspaceOwner or workspaceUser with administrative privileges. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/abort_exec_request.sql auditId workspace;

- For an auditId that represents a running job, this script aborts the job cleanly. The auditId may be obtained by running the list_requests.sql script; see "list_requests".

- The workspace is the workspace where the job is running, and should be declared as workspaceOwner.workspaceName. If using only the workspaceName, workspaceOwner defaults to current user.

abort_unit_request

The abort_unit_request.sql script terminates a deployment job at the unit level. A deployment unit is a collection of objects that are being deployed to the same location with the same deployment action.

Connect as workspaceOwner or workspaceUser with administrative privileges. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/abort_unit_request.sql auditId workspace;

- For an auditId that represents a deployment unit job, this script aborts the job cleanly. The auditId may be obtained by running the list_requests.sql script; see "list_requests".

- The workspace is the workspace where the job is running, and should be declared as workspaceOwner.workspaceName. If using only the workspaceName, workspaceOwner defaults to current user.

deactivate_all

The deactivate_all.sql script deactivates all incomplete deployment and execution jobs.

Connect as workspaceOwner or workspaceUser with administrative privileges. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/deactivate_all.sql workspace;

- The workspace is the workspace where the job is running, and should be declared as workspaceOwner.workspaceName. If using only the workspaceName, workspaceOwner defaults to current user.

deactivate_deployment

The deactivate_deployment.sql script deactivates a deployment job.

Connect as workspaceOwner or workspaceUser with administrative privileges. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/deactivate_deployment.sql auditId workspace;

- For an auditId that represents a deployment job, this script deactivates the job and all its unit jobs cleanly. The auditId may be obtained by running the list_requests.sql script; see "list_requests".

- The workspace is the workspace where the job is running, and should be declared as workspaceOwner.workspaceName. If using only the workspaceName, workspaceOwner defaults to current user.

deactivate_execution

The deactivate_execution.sql script deactivates an execution job.

Connect as workspaceOwner or workspaceUser with administrative privileges. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/deactivate_execution.sql auditId workspace;

- For an auditId that represents an execution job, this script deactivates the job cleanly. The auditId may be obtained by running the list_requests.sql script; see "list_requests".

- The workspace is the workspace where the job is running, and should be declared as workspaceOwner.workspaceName. If using only the workspaceName, workspaceOwner defaults to current user.

delete_warehouse_object

The delete_warehouse_object.sql script deletes a warehouse object.

Connect as workspaceOwner or workspaceUser with administrative privileges. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/delete_warehouse_object.sql object location workspace;

- The named object is deleted.

- The location is where the object may be found.

- The workspace is the workspace where the job is running, and should be declared as workspaceOwner.workspaceName. If using only the workspaceName, workspaceOwner defaults to current user.

display_platform_property

The display_platform_property.sql script displays the value of a platform property. These properties control the behavior of the control center service.

Connect as workspaceOwner or workspaceUser with administrative privileges. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/display_platform_property.sql property;

- The script assumes that at most one property with the given name exists. To set the property, see "set_platform_property".

expedite_exec_request

The expedite_exec_request.sql script expedites a running job by moving it to the top of the list of pending jobs.

Connect as workspaceOwner or workspaceUser with execute, deploy, and administrative privileges. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/expedite_exec_request.sql authId returnNumber returnCode workspace;

- For an auditId that represents a deployment job, this script expedites the job cleanly. The auditId may be obtained by running the list_requests.sql script; see "list_requests".

- The returnNumber and returnCode are the result values assigned to the job, and have the following values:

- 0 = OK

- 1 = OK_WITH_WARNINGS

- 3 = FAILURE

- The workspace is the workspace where the job is running, and should be declared as workspaceOwner.workspaceName. If using only the workspaceName, workspaceOwner defaults to current user.

grant_error_table_privileges

The grant_error_table_privileges.sql script enables the Repository Browser to view and purge error tables. It grants SELECT and DELETE privileges on the specified table to the OWBSYS user.

Connect as the user who owns the error table. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/grant_error_table_privileges.sql tableName;

- In this script, tableName is the name of the error table, such as TABLE1_ERR.

grant_upgrade_privileges

The grant_upgrade_privileges.sql script grants the required roles and privileges for upgrading deployment actions to a specific user.

Connect as workspaceOwner or workspaceUser with execute, deploy, and administrative privileges, such as SYS. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/grant_upgrade_privileges.sql userName;

- In this script, userName is the name of the schema or user who has the new upgrade privileges.

list_requests

The list_requests.sql script lists the details of any active deployment or execution requests. A deployment is a collection of deployment units, which are collections of objects deployed by the same deployment action to the same location. Each deployment or execution is uniquely identified by an audit ID that may be used as a parameter to other SQL scripts, such as "deactivate_deployment", "deactivate_execution", and so on.

Connect as workspaceOwner or workspaceUser with execute, deploy, and administrative privileges. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/list_requests.sql workspace;

- The workspace is the workspace where the job is running, and should be declared as workspaceOwner.workspaceName. If using only the workspaceName, workspaceOwner defaults to current user.

print_exec_details

The print_exec_details.sql script prints the audit execution hierarchy and details about the various executions associated with an auditId to a file called exec_details.txt.

Connect as workspaceOwner or workspaceUser with execute, deploy, and administrative privileges. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/print_exec_details.sql auditId workspace;

- The auditId represents an execution job about which this script print the job details. The auditId may be obtained by running the script list_requests.sql; see "list_requests".

- The workspace is the workspace where the job is running, and should be declared as workspaceOwner.workspaceName. If using only the workspaceName, workspaceOwner defaults to current user.

print_running_exec_details

The print_running_exec_details.sql script prints the audit execution hierarchy and details about the various incomplete executions that were started after the specified date associated with an auditId to a file called exec_details.txt.

Connect as workspaceOwner or workspaceUser with execute, deploy, and administrative privileges. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/print_running_exec_details.sql auditId workspace;

- The auditId represents an execution job about which this script print the job details. The auditId may be obtained by running the script list_requests.sql; see "list_requests".

- The workspace is the workspace where the job is running, and should be declared as workspaceOwner.workspaceName. If using only the workspaceName, workspaceOwner defaults to current user.

purge_audit_template

The purge_audit_template.sql script purges either deployment audit data or execution audit data.

Connect as workspaceOwner or workspaceUser with administrative privileges. The script is of the form:

SQL> @drive:OWB_HOME/owb/rtp/sql/purge_audit_template.sql
workspace
{DEPLOYMENT | EXECUTION}
{sql_predicate | ALL | DATE_RANGE} [start_date end_date];

- The workspace is the workspace where the job is running, and should be declared as workspaceOwner.workspaceName. If using only the workspaceName, workspaceOwner defaults to current user.

- The audit_type is one of:

- DEPLOYMENT for deployment audit data; see columns in ALL_RT_AUDIT_DEPLOYMENTS view

- EXECUTION for execution audit data; see columns in ALL_RT_AUDIT_EXECUTIONS view

- The condition can be one of:

- sql_predicate, such as "number_script_run_errors > 0"; this must follow with SQL syntax rules

- ALL, for purging all deployment or execution data

- DATE_RANGE, for purging data within a specified data range

- If DATE_RANGE is used, start_date is the start of date range (such as TO_DATE('01-Jan-08') and end_date is the end of the date range (such as SYSDATE).

There are several ways to invoke this script, as demonstrated in these examples:

SQL> @drive:OWB_HOME/owb/rtp/sqlpurge_audit_template.sql
workspace DEPLOYMENT ALL null null

SQL> @drive:OWB_HOME/owb/rtp/sqlpurge_audit_template.sql
workspace EXECUTION "number_task_errors > 0" null null

SQL> @drive:OWB_HOME/owb/rtp/sqlpurge_audit_template.sql
workspace EXECUTION DATE_RANGE TO_DATE('01-Jan-2008') SYSDATE

reset_repository

The reset_repository.sql script resets the registration details for an Oracle Warehouse Builder repository. It also stores the specified password as the password for the repository; see "set_repository_password". After the registration details are reset, you must register the passwords for all previously registered locations.

Connect as repository owner, OWBSYS. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/reset_repository.sql password

rtrepos_report

The rtrepos_report.sql script displays the details of the Control Center and its registered locations. It provides information before using the location_util.bat script to alter some stored credentials.

Connect as repository owner, OWBSYS. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/rtrepos_report.sql

service_doctor

The service_doctor.sql script displays diagnostics about Oracle Warehouse Builder repository and its Control Center Service.

Connect as repository owner, OWBSYS. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/service_doctor.sql

set_ccs_home

The set_ccs_home.sql script sets the properties associated with a Control Center Service to recognize the location of the where to pick up the Instance Number, Version and Server Side Home. These parameters are not included in an Oracle Warehouse Builder Installation when the "Allow Local Control Center Service" option is set.

Connect as repository owner, OWBSYS. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/set_ccs_home.sql instance version server_home

- The instance is the service node instance that you are updating

- The version is Oracle Warehouse Builder version that you are using

- The server_home is Oracle Warehouse Builder Home on the server computer, where Oracle Warehouse Builder install components are located.

set_platform_property

The set_platform_property.sql script sets the value of a platform property. These properties controls the behavior of the Control Center Service.

The script assumes that the specified property must exist and its value is mutable.

Connect as repository owner, OWBSYS. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/set_platform_property.sql
property property_value

- The property is the name of the property that is changed

- The property_value is the name of the new value of the property

- To return a list of the properties, execute the following query:

select property_path from wb_rt_platform_properties where is_mutable <> 0

set_platform_property_from_file

The set_platform_property_from_file.sql script sets the value of a platform property to the contents of the file_name found in the directory. These properties controls the behavior of the Control Center Service.

The script assumes that the specified property must exist and its value is mutable.

Connect as Control Center owner. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/set_platform_property_from_file.sql property directory file_name

- The property is the name of the property that is changed.

- The directory is the path where the new value for the property can be found.

- The file_name is the name of the file that contains the new value of the property.

set_repository_password

The set_repository_password.sql script sets the password for Oracle Warehouse Builder repository. This password is used by the Control Center Service at startup time.

Connect as repository owner, OWBSYS. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/set_repository_password.sql password

- The password is the new password value.

show_service

The show_service.sql script displays the status of the Control Center Service, which provides access to the deployment and execution features of an Oracle Warehouse Builder repository. The valid return values for the status of the Control Service Center are Available or Not Available. To change the status of the Control Center Service, use the SQL scripts start_service and stop_service as appropriate.

Connect as repository owner, OWBSYS. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/show_service.sql

sqlplus_exec_background_template

The sqlplus_exec_background_template.sql script runs the specified object in the background, not blocking the caller. To get the task status and return result, check public views, of the type ALL_RT_*. Use the script "sqlplus_exec_template" to run the object in the foreground, which blocks the caller until the completion of the task. In its unchanged form the script takes the three keys required to identify the executable task. The task runs in the background with the default parameters configured before deployment. The custom_params (defined on the object in Oracle Warehouse Builder Designer) and system_params values override the default input parameters of the task. The script returns the following values: 1 if task reports SUCCESS, 2 if WARNING, 3 if ERROR.

Connect as workspaceOwner or workspaceUser with execute privilege. The script is of the form:

SQL> @drive:OWB_HOME/owb/rtp/sql/sqlplus_exec_background_template.sql
workspace
location_name
{PLSQLMAP | SQLLOADERCONTROLFILE | PROCESSFLOW | ABAPFILE |
DATAAUDITOR | SCHEDULEDJOB}
[parent/]task_name
system_params
custom_params

- The workspace is nominated in the parameters, and should be declared as workspaceOwner.workspaceName; if using only workspaceName, workspaceOwner defaults to user.

- The location_name is the physical name of the location to which the task is deployed.

- The task_type has the following options:

- PLSQLMAP is used for Oracle Warehouse Builder PL/SQL mapping.

- SQLLOADERCONTROLFILE is used for Oracle Warehouse Builder SQL*Loader mapping.

- PROCESSFLOW is used for Oracle Warehouse Builder ProcessFlow.

- ABAPFILE is used for Oracle Warehouse Builder SAP mapping.

- DATAAUDITOR is used for Oracle Warehouse Builder DataAuditor mapping.

- SCHEDULEDJOB is used for an Oracle Warehouse Builder scheduled job.

- CTMAPPING is used for Oracle Warehouse Builder Code Template mapping.

- The task_name is the physical name of the deployed object; it can be optionally named of the deployed parent, like the ProcessFlow package name. A module name cannot be used because it is not a deployable object.

- The custom_params (defined on the object in Oracle Warehouse Builder Designer) and system_params values override the default input parameters of the task

If you encounter problems accessing public views, then connect to SQL*Plus using your repository user or owner credentials, and issue:

Set role OWB_USER

Run @start_access_workspace.sql workspaceName workspaceOwner. You can then access the public views.

There are several ways to invoke this script; note that system_params and custom_params are not used in these examples:

SQL> @drive:OWB_HOME/owb/rtp/sql/sqlplus_exec_background_template.sql
workspace warehouse PLSQL mapping "," ","

SQL> @drive:OWB_HOME/owb/rtp/sql/sqlplus_exec_background_template.sql
workspace platform_schema SQL_LOADER load "," ","

SQL> @drive:OWB_HOME/owb/rtp/sql/sqlplus_exec_background_template.sql
workspace workflow PROCESS process_1 "," ","

SQL> @drive:OWB_HOME/owb/rtp/sql/sqlplus_exec_background_template.sql
workspace platform_schema SAP sap_1 "," ","

SQL> @drive:OWB_HOME/owb/rtp/sql/sqlplus_exec_background_template.sql
workspace warehouse DATA_AUDITOR data_auditor_1 "," ","

Note: The comma character can be escaped using the backslash character (\,); likewise the backslash character can be escaped by using two backlash characters (\\). A single-quote character must be replaced by a sequence of four single-quote characters ('''').

sqlplus_exec_template

The sqlplus_exec_template.sql script runs the specified object and blocks the caller until the task is completed. To get the task status and return result, check public views of the type ALL_RT_*. Use the script "sqlplus_exec_background_template" to run the object in the background, without blocking the caller throughout the completion of the task. The script takes the three keys required to identify the executable task. The task runs with the default parameters configured before deployment. The custom_params (defined on the object in the Oracle Warehouse Builder Designer) and system_params values override the default input parameters of the task. The script returns the following values: 1 if task reports SUCCESS, 2 if WARNING, 3 if ERROR.

Connect as workspaceOwner or workspaceUser with execute privilege. The script is of the form:

SQL> @drive:OWB_HOME/owb/rtp/sql/sqlplus_exec_template.sql
workspace
location_name
{PLSQLMAP | SQLLOADERCONTROLFILE | PROCESSFLOW | ABAPFILE |
DATAAUDITOR | SCHEDULEDJOB}
[parent/]task_name
system_params
custom_params

- The workspace is nominated in the parameters, and should be declared as workspaceOwner.workspaceName; if using only workspaceName, workspaceOwner defaults to user.

- The location_name is the physical name of the location to which the task is deployed.

- The task_type has the following options:

- PLSQLMAP is used for Oracle Warehouse Builder PL/SQL mapping.

- SQLLOADERCONTROLFILE is used for Oracle Warehouse Builder SQL*Loader mapping.

- PROCESSFLOW is used for Oracle Warehouse Builder Process Flow.

- ABAPFILE is used for Oracle Warehouse Builder SAP mapping.

- DATAAUDITOR is used for Oracle Warehouse Builder Data Auditor mapping.

- SCHEDULEDJOB is used for an Oracle Warehouse Builder scheduled job.

- CTMAPPING is used for Oracle Warehouse Builder Code Template mapping.

- The task_name is the physical name of the deployed object; it can be optionally qualified named of the deployed parent, like the ProcessFlow package name. A module name cannot be used because it is not a deployable object.

- The custom_params (defined on the object in Oracle Warehouse Builder Designer) and system_params values override the default input parameters of the task

There are several ways to invoke this script; note that system_params and custom_params are not used in these examples:

SQL> @drive:OWB_HOME/owb/rtp/sql/sqlplus_exec_template.sql
workspace warehouse PLSQL mapping "," ","

SQL> @drive:OWB_HOME/owb/rtp/sql/sqlplus_exec_template.sql
workspace platform_schema SQL_LOADER load "," ","

SQL> @drive:OWB_HOME/owb/rtp/sql/sqlplus_exec_template.sql
workspace workflow PROCESS process_1 "," ","

SQL> @drive:OWB_HOME/owb/rtp/sql/sqlplus_exec_template.sql
workspace platform_schema SAP sap_1 "," ","

SQL> @drive:OWB_HOME/owb/rtp/sql/sqlplus_exec_template.sql
workspace warehouse DATA_AUDITOR data_auditor_1 "," ","

Note: The comma character can be escaped using the backslash character (\,); likewise the backslash character can be escaped by using two backlash characters (\\). A single-quote character must be replaced by a sequence of four single-quote characters ('''').

start_service

The script start_service.sql starts a Control Center Service that is managed by the database. A Control Center Service, when available, provides access to the deployment and execution features of an Oracle Warehouse Builder repository. To determine if the Control Center Service is available, use the show_service script; the return values are either Available or Not Available. To stop the service, use the stop_service script. When the service is invoked using this script, a monitoring job is created; it restarts the service if it fails, or if the database is brought back online. Alternatively, a Control Center Service can be started in a different OWB_HOME, on another host; the service is available only when that host is available and provided the service has been started and not stopped.

Connect as repository owner, OWBSYS. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/start_service.sql

stop_service

The script stop_service.sql stops a Control Center Service that is managed by the database. A Control Center Service, when available, provides access to the deployment and execution features of an Oracle Warehouse Builder repository. To determine if the Control Center Service is available, use the show_service script; the return values are either Available or Not Available. To start the service, use the start_service script. When the service is stopped using this script, the monitoring job is removed; the service remains disabled until it is re-started by the start_service script.

Connect as repository owner, OWBSYS. Run the script:

SQL> @drive:OWB_HOME/owb/rtp/sql/stop_service.sql

UpdateControlCenter

This SQL script sets the host:port:service parameters for a control center in the Oracle Warehouse Builder Client Repository. The connection type must be host:port:service.

UpdateLocation

This SQL script sets the host:port:service parameters for a location in Oracle Warehouse Builder Client Repository. The connection type must be host:port:service. The location may be registered or unregistered.

Overview of Oracle Warehouse Builder Repository Browser

The Repository Browser is a browser-based tool that generates reports from data stored in Oracle Warehouse Builder repositories. When you install Oracle Warehouse Builder from Oracle Universal Installer, the Repository Browser is also installed and runs in all the languages that you select during installation.

Starting the Repository Browser

The Repository Browser can be started if the Repository Browser Listener is in a running mode. You can start the Repository Browser in any of the following ways:

- On a Windows platform, from the Start menu, select Programs. Select the Warehouse Builder folder, and then Warehouse Builder Repository Browser.

- From the Tools menu of the Design Center, select Repository Browser.

- In the web browser, type the location of the Repository Connection page. For example, if the Repository Browser Listener is running on a computer named owbserver, then type the following address to start the Repository Browser.

https://owbserver/:8999/owbb_RABLogin.uix?mode=runtime
OR
https://owbserver/:8999/owbb_RABLogin.uix?mode=design

It starts the Repository Browser.

After the Repository Browser is started, the browser opens the Repository connection page that helps us to log in to the Repository Browser.

How to Start the Repository Browser Listener

Before you can open the Repository Browser, you must start the Repository Browser Listener.

Starting the Repository Browser Listener in Windows

Open a command prompt window and run startOwbbInst.bat located in the OWB_HOME\owb\bin\win32 directory. You are prompted to set the password for the OC4J administrator. Enter a password and press the Enter key. When you are prompted to confirm the password, enter the same password again.

Starting the Repository Browser Listener in UNIX/LINUX

Run ./startOwbbInst.sh located in the OWB_HOME/owb/bin/unix directory. You are prompted to set the password for the OC4J administrator. Enter a password and press the Enter key. When you are prompted to confirm the password, enter the same password again.

How to Stop the Repository Browser Listener

To stop the Repository Browser Listener, do the following.

Stopping the Repository Browser Listener in Windows

Open a command prompt window and run stopOwbbInst.bat located in the OWB_HOME\owb\bin\win32 directory. You are prompted to provide the OC4J administrator password that you set while starting the Repository Browser Listener. Type the password and press the Enter key.

Stopping the Repository Browser Listener in UNIX and Linux

Run ./stopOWBBInst.sh located in the OWB_HOME/owb/bin/unix directory. You are prompted to provide the OC4J administrator password that you set while starting the Repository Browser Listener. Type the password and press the Enter key.

10 Managing the Control Center Agent

This section describes how to start and stop the Control Center Agent (CCA), and how to administer it using the cca_admin utility. The CCA manages deployment and execution of the mappings that are based on Code Templates. CCA is not part of the Control Center service hosted within the Oracle Database.

This section contains the following topics:

- "Starting and Stopping the Control Center Agent"

- "About the cca_admin Utility"

- "Starting the cca_admin Utility"

- "cca_admin Commands"

See Also:

- Chapter 7, "Configuring Repository Browser, Control Center Agent, and Other Components", and specifically section "Configuring Control Center Agent Server-side Logging" if you have your own Oracle Application Server and want to install the CCA there.

- Chapter 7, "Configuring Repository Browser, Control Center Agent, and Other Components" for procedures that modify the installation defaults.

Starting and Stopping the Control Center Agent

This section describes how to start and stop the CCA.

When you invoke the ccastart for the first time, it prompts you to enter a password for the OC4J administrator account. The default user name for this account is oc4jadmin.

To start the CCA:

- On UNIX, in the directory OWB_HOME /owb/bin/unix/, run the script ccastart.

- On Windows, in the directory OWB_HOME\owb\bin\win32\, run the script ccastart.bat.

To stop the CCA:

- On UNIX, in the directory OWB_HOME /owb/bin/unix/, run the script ccashut. This script accepts an optional argument password..

- On Windows, in the directory OWB_HOME\owb\bin\win32\, run the script ccashut.bat. This script accepts an optional argument password.

For a representation of architectural structures of this installation, see Figure 1-5, "Control Center Agent Topology".

For procedures that modify installation defaults, see Chapter 7, "Configuring Repository Browser, Control Center Agent, and Other Components".

About the cca_admin Utility

The cca_admin utility changes Control Center Agent settings dynamically, without the requirement to shut down and subsequently restart the run-time environment. cca_admin commands retrieve the values of various environment attributes, set these to new values, and invoke the operations of JRTAdministratorMBean, introduced in section "JRTAdministratorMBean".

The typical cca_admin session includes the following steps:

- Running the cca_admin script, as described in "Starting the cca_admin Utility".

- Connecting to an MBeanServer using the connect command described in "connect".

- Issuing one or more commands to view or update run-time environment attributes or invoke cca_admin commands described in "cca_admin Commands".

- Disconnecting from the server using the command "disconnect" or the command "exit".

Starting the cca_admin Utility

The cca_admin tool is delivered as a shell script on Linux or a batch file on Windows.

- On UNIX, use the following command:
OWB_HOME /owb/bin/unix/cca_admin

- On Windows, use the following command:
OWB_HOME\owb\bin\win32\cca_admin.bat.

Before activating the JRTAdministratorMBean, your can use only the basic commands: help, connect, disconnect, and exit. The full range of commands is available after you connect to an MBean server and start using the JRTAdministratorMBean.

cca_admin Commands

This section provides a complete list of the cca_admin commands as follows:

- "cleanUpJobLogFilesForGivenTimeInterval"

- "cleanUpNLeastRecentJobLogFiles"

- "connect"

- "disconnect"

- "exit"

- "getCacheJobStatusSize"

- "getCacheLogNo"

- "getKmPermissionsFile"

- "getLogRoot"

- "getMaxAbortTimeout"

- "getMaxRuntimeFileSizeMB"

- "getMaxRuntimeLogSizeMB"

- "getRuntimeLogEncoding"

- "getRuntimeLogFileLocation"

- "getRuntimeLogLevel"

- "help"

- "isKmSecurityNeeded"

- "isLogToAuditTable"

- "isLogToOdl"

- "isShowRuntimeLoggerLogHostAddr"

- "isShowRuntimeLoggerLogHostId"

- "isShowRuntimeLoggerLogMsgClassPath"

- "isShowRuntimeLoggerLogMsgLogLevel"

- "isShowRuntimeLoggerLogUserId"

- "readSettings"

- "reset"

- "setCacheJobStatusSize"

- "setCacheLogNo"

- "setKmPermissionsFile"

- "setKmSecurityNeeded"

- "setLogRoot"

- "setLogToAuditTable"

- "setLogToOdl"

- "setRuntimeLogEncoding"

- "setMaxAbortTimeout"

- "setMaxRuntimeFileSizeMB"

- "setMaxRuntimeLogSizeMB"

- "setRuntimeLogLevel"

- "setShowRuntimeLoggerLogHostAddr"

- "setShowRuntimeLoggerLogHostId"

- "setShowRuntimeLoggerLogMsgClassPath"

- "setShowRuntimeLoggerLogMsgLogLevel"

- "setShowRuntimeLoggerLogUserId"

- "settingsToString"

- "showAllJobLogFiles"

cleanUpJobLogFilesForGivenTimeInterval

This command removes all log files that were modified during the specified time range, between startDate and endDate, and returns the total number of files removed. Both parameters are expressed in the format DD-MM-YYYY HH:MM:SS. If the specified startDate is null, no records are deleted. If endDate is null, all log files created after the startDate are purged.

Example 10-1 Using cleanUpJobLogFilesForGivenTimeInterval Command

cleanUpJobLogFilesForGivenTimeInterval 26-12-2008 13:38:56 12-01-2009 22:15:58

cleanUpNLeastRecentJobLogFiles

This command removes the specified number n, of least recent log files from the system, and returns the number of job log files that are actually removed.

Example 10-2 Using cleanUpNLeastRecentJobLogFiles command

cleanUpNLeastRecentJobLogFiles 10

connect

This command connects the user to MBean server.

The command is of the following form, where host is the computer on which the CCA is located, port is the port number for accessing the CCA, user is the user name for accessing the CCA, password is that user's password, connection_type is one of RMI, OPMN, RMIS, OPMN_RMIS, OPMN_CLUSTER, or OPMN_CLUSTER_RMIS, application_name is the name of the application deployed to OC4J, and instance is the OC4J process that contains the CCA application:

connect host port user password connection_type application_name instance

Example 10-3 Using connect Command

connect localhost 23791 oc4jadmin welcome rmi jrt host

disconnect

This command disconnects the user from the MBean server.

Example 10-4 Using disconnect Command

disconnect

exit

This command exits the cca_admin shell when it is running in the interactive mode. If the connection to the MBean server is not closed, it first disconnects and then exits cca_admin shell.

Example 10-5 Using exit Command

exit

getCacheJobStatusSize

This command returns a value for the number (integer) MBean attribute CacheJobStatusSize, which controls the maximum number of the job status logs that can be stored by the in-memory job log cache in CCA. The attribute's value is in the range of 1 and 10000, with the default value of 3000.

Example 10-6 Using getCacheJobStatusSize Command

getCacheJobStatusSize 3000

getCacheLogNo

This command returns the value of MBean attribute CacheLogNo, which controls the maximum number of job logs that can be stored by the in-memory job log cache in CCA. Obviously the bigger this number is the more memory CCA takes up. The attribute's value is in the range of 1 and 100, with the default value of 10.

Example 10-7 Using getCacheLogNo Command

getCacheLogNo

getKmPermissionsFile

This command returns the value of MBean attribute KmPermissionsFile, which is the file system path to the ct_permissions.properties file. If this parameter is set to true, the CCA checks ct_permissions.properties to determine what system commands may be executed. This path may be either absolute or relative. The relative value refers to the $OC4J_HOME/j2ee/home directory. The default value is config/ct_permissions.properties.

Example 10-8 Using getKmPermissionsFile Command

getKmPermissionsFile

getLogRoot

This command returns the value of MBean attribute LogRoot, which is the directory that stores the CCA job log file. The attribute value may be either absolute or relative. The relative value refers to $OC4J_HOME/j2ee/home directory; the default value is $OC4J_HOME/j2ee/home/log.

Example 10-9 Using getLogRoot Command

getLogRoot

getMaxAbortTimeout

Returns the value of MBean attribute MaxAbortTimeout, the maximum amount of wait time in seconds before the execution is aborted. The attribute's value is in the range of 1 to 60; and the default value is 60.

Example 10-10 Using getMaxAbortTimeout Command

getMaxAbortTimeout

getMaxRuntimeFileSizeMB

This command returns the value of MBean attribute MaxRuntimeFileSizeMB, the maximum size of any log file, in MB. When a log file exceeds this limit, it is closed and a new log file is opened. The attribute's value is in the range of 1 MB to 15 MB, and the default value is 3 MB.

Example 10-11 Using getMaxRuntimeFileSizeMB Command

getMaxRuntimeFileSizeMB

getMaxRuntimeLogSizeMB

This command returns the value of MBean attribute MaxRuntimeLogSizeMB, the maximum size of the log file directory, in MB. When the directory exceeds this limit, log files are purged, starting with the oldest. The attribute's value is in the range of 1 MB to 20 MB, and the default value is 10 MB.

Example 10-12 Using getMaxRuntimeLogSizeMB Command

getMaxRuntimeLogSizeMB

getRuntimeLogEncoding

This command returns the value of MBean attribute RuntimeLogEncoding, which specifies the character encoding of the log file. The default value is UTF-8.

Example 10-13 Using getRuntimeLogEncoding Command

getRuntimeLogEncoding

getRuntimeLogFileLocation

This command returns the value of MBean attribute RuntimeLogFileLocation, the name of CCA job log file, a read-only attribute. This value is $OC4J_HOME/j2ee/home/log/appName.log, where appName is the name of the CCA application.

Example 10-14 Using getRuntimeLogFileLocation Command

getRuntimeLogFileLocation

getRuntimeLogLevel

This application returns the value of MBean attribute RuntimeLogLevel, the log level for run-time logger. The legal values for this attribute are: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL (default).

Example 10-15 Using getRuntimeLogLevel Command

getRuntimeLogLevel

help

This command returns help information for a specified valid command; if a command is not specified, it returns the list of valid commands.

Example 10-16 Using help Command

help
help isLogToOdl

isKmSecurityNeeded

This command returns the value of MBean attribute KmSecurityNeeded, determining whether security is enforced on system commands that are invoked by CCA script. If the value is true (which is the default), CCA checks the ct_permissions.properties file for allowable system commands, and only execute the commands defined in ALLOWED_CMD. If the value is false, CCA executes all system commands.

Example 10-17 Using isKmSecurityNeeded Command

isKmSecurityNeeded

isLogToAuditTable

This command returns the value of MBean attribute LogToAuditTable, which turns audit table logging on and off. Audit table logging is only effective for execution job logs. The attribute value is either true or false.

Example 10-18 Using isLogToAuditTable Command

isLogToAuditTable

isLogToOdl

This command returns the value of MBean attribute LogToOdl, which turns ODL logging on and off. Only effective for execution job logs. Deployment and Web service logs are always created in the ODL log format, regardless of the value of this setting. The attribute value is either true or false.

Example 10-19 Using isLogToOdl Command

isLogToOdl

isShowRuntimeLoggerLogHostAddr

This command returns the value of MBean attribute ShowRuntimeLoggerLogHostAddr, which determines whether the IP address of the host that is running CCA is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-20 Using isShowRuntimeLoggerLogHostAddr Command

isShowRuntimeLoggerLogHostAddr

isShowRuntimeLoggerLogHostId

This command returns the value of MBean attribute ShowRuntimeLoggerLogHostId, which determines whether the ID of the host that is running CCA is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-21 Using isShowRuntimeLoggerLogHostId Command

isShowRuntimeLoggerLogHostId

isShowRuntimeLoggerLogMsgClassPath

This command returns the value of MBean attribute ShowRuntimeLoggerLogMsgClassPath, which determines whether the path of the class where the message is logged is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-22 Using isShowRuntimeLoggerLogMsgClassPath Command

isShowRuntimeLoggerLogMsgClassPath

isShowRuntimeLoggerLogMsgLogLevel

This command returns the value of MBean attribute ShowRuntimeLoggerLogMsgLogLevel, which determines whether the log level of the log message is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-23 Using isShowRuntimeLoggerLogMsgLogLevel Command

isShowRuntimeLoggerLogMsgLogLevel

isShowRuntimeLoggerLogUserId

This command returns the value of MBean attribute ShowRuntimeLoggerLogUserId, which determines whether the ID of the user is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-24 Using isShowRuntimeLoggerLogUserId Command

isShowRuntimeLoggerLogUserId

readSettings

This command reads CCA settings from the CCA configuration file.

Example 10-25 Using readSettings Command

readSettings

reset

This command resets attributes to their default values, if the attributes are defined to have defaults.

Example 10-26 Using reset Command

reset

setCacheJobStatusSize

This command sets the value for MBean attribute CacheJobStatusSize, which controls the maximum number of the job status that can be stored in the in-memory job log cache in CCACCA. The attribute's value is an integer in the range of 1 to 10000; the default value is 3000.

Example 10-27 Using setCacheJobStatusSize Command

setCacheJobStatusSize 3000

setCacheLogNo

This command sets a value for MBean attribute CacheLogNo, which controls the maximum number of job logs that can be stored in the in-memory job log cache in CCA. The attribute's value is an integer in the range of 1 and 100; the default value is 10.

Example 10-28 Using setCacheLogNo Command

setCacheLogNo 10

setKmPermissionsFile

This command sets the value for MBean attribute KmPermissionsFile, which is the file system path to the ct_permissions.properties file. If the value is set to true, the CCA checks the file to determine what system commands may run. The path can be either absolute or relative. The relative refers to $OC4J_HOME/j2ee/home directory; the default value is config/ct_permissions.properties.

Example 10-29 Using setKmPermissionsFile Command

setKmPermissionsFile $OC4J_HOME/j2ee/home/config/ct_permissions.properties

setKmSecurityNeeded

This command sets a value for MBean attribute KmSecurityNeeded, which determines whether security is enforced on system commands invoked from CCA scripts. When the value is true (default), CCA checks the ct_permissions.properties file for system commands that may run, and only execute the ones defined in ALLOWED_CMD. When the value is false, CCA runs all system commands.

Example 10-30 Using setKmSecurityNeeded Command

setKmSecurityNeeded true
setKmSecurityNeeded false

setLogRoot

This command sets the value of MBean attribute LogRoot, the directory of the CCA job log file. The attribute's value may be either absolute or relative. The relative value refers to $OC4J_HOME/j2ee/home directory; the default value is $OC4J_HOME/j2ee/home/log.

Example 10-31 Using setLogRoot Command

setLogRoot $OC4J_HOME/j2ee/home/log

setLogToAuditTable

This command sets the value for MBean attribute LogToAuditTable, which turns audit table logging on and off. Audit table logging is only effective for execution job logs. The attribute's value is true or false.

Example 10-32 Using setLogToAuditTable Command

setLogToAuditTable true
setLogToAuditTable false

setLogToOdl

This command sets the value for MBean attribute LogToOdl, which turns ODL logging on and off. This is only effective for execution job logs; deployment and Web service logs are created in ODL log format regardless of this setting. The attribute's value is true or false.

Example 10-33 Using setLogToOdl Command

setLogToOdl true
setLogToOdl false

setMaxAbortTimeout

This command sets the value for MBean attribute MaxAbortTimeout, the maximum wait time (in seconds) before aborting the execution. The attribute's value is an integer in the range of 1 to 60 (default).

Example 10-34 Using setMaxAbortTimeout command

setMaxAbortTimeout 60

setMaxRuntimeFileSizeMB

This command sets the value of MBean attribute MaxRuntimeFileSizeMB, the maximum size, in MB, a log file in the directory. When a log file exceeds this limit, it is closed and a new log file is opened. The attribute's value is an integer in the range of 1 MB and 15 MB; the default value is 3 MB.

Example 10-35 Using setMaxRuntimeFileSizeMB Command

setMaxRuntimeFileSizeMB 5

setMaxRuntimeLogSizeMB

This command sets the value of MBean attribute MaxRuntimeLogSizeMB, the maximum size of the log file directory, in MB. When the directory exceeds this limit, log files are purged, starting with the oldest. The attribute's value is in the range of 1 MB to 20 MB, and the default value is 10 MB.

Example 10-36 Using setMaxRuntimeLogSizeMB Command

setMaxRuntimeLogSizeMB 10

setRuntimeLogEncoding

This command sets the value of MBean attribute RuntimeLogEncoding, which specifies the character set encoding of the log file. The default value is UTF-8.

Example 10-37 Using setRuntimeLogEncoding Command

setRuntimeLogEncoding UTF-8

setRuntimeLogLevel

This command sets the value for MBean attribute RuntimeLogLevel, the log level for run-time logger. The attribute's value may be SEVERE,WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL (default).

Example 10-38 Using setRuntimeLogLevel Command

setRuntimeLogLevel ALL

setShowRuntimeLoggerLogHostAddr

This command sets the value for MBean attribute ShowRuntimeLoggerLogHostAddr, which determines whether the IP address of the CCA host is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-39 Using setShowRuntimeLoggerLogHostAddr Command

setShowRuntimeLoggerLogHostAddr true
setShowRuntimeLoggerLogHostAddr false

setShowRuntimeLoggerLogHostId

This command sets the value for MBean attribute ShowRuntimeLoggerLogHostId, which determines whether the ID of the CCA host is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-40 Using setShowRuntimeLoggerLogHostId Command

setShowRuntimeLoggerLogHostId true
setShowRuntimeLoggerLogHostId false

setShowRuntimeLoggerLogMsgClassPath

This command sets the value for MBean attribute ShowRuntimeLoggerLogMsgClassPath, which determines whether the path of the class that logged the message is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-41 Using setShowRuntimeLoggerLogMsgClassPath Command

setShowRuntimeLoggerLogMsgClassPath true
setShowRuntimeLoggerLogMsgClassPath false

setShowRuntimeLoggerLogMsgLogLevel

This command sets the value for MBean attribute ShowRuntimeLoggerLogMsgLogLevel, which determines whether the log level of the log message is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-42 Using setShowRuntimeLoggerLogMsgLogLevel Command

setShowRuntimeLoggerLogMsgLogLevel true
setShowRuntimeLoggerLogMsgLogLevel false

setShowRuntimeLoggerLogUserId

This command sets the value for MBean attribute ShowRuntimeLoggerLogUserId, which determines whether the ID of the user is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-43 Using setShowRuntimeLoggerLogUserId Command

setShowRuntimeLoggerLogUserId true
setShowRuntimeLoggerLogUserId false

settingsToString

This command converts CCA setting information to String, and shows all CCA settings.

Example 10-44 Using settingsToString Command

settingsToString

showAllJobLogFiles

This command shows all job log files names.

Example 10-45 Using showAllJobLogFiles Command

showAllJobLogFiles

11 Using Snapshots to Manage Metadata

This section describes how to use snapshots to manage metadata. Snapshots in Oracle Warehouse Builder enable you to capture point-in-time versions of the metadata definitions of the design objects you create in the Project Navigator. You can capture all design objects in a project, or you can selectively choose objects to include in a snapshot.

This section includes the following topics:

- "About Snapshots and Metadata Loader"

- "Using Snapshots"

About Snapshots and Metadata Loader

Because snapshots and the Metadata Loader have overlapping capabilities, it may not be readily apparent when to use one and not the other. In general, snapshots address the needs of a development team for tracking changes to an evolving design. The Metadata Loader facilitates the more traditional administrative tasks of backing up, restoring, and migrating repositories.

A key factor to understand is that snapshots and the Metadata Loader differ in the scope of objects they handle. Snapshots are limited to handling only the design objects users create in the Project Navigator. The Metadata Loader, however, handles everything in the repository. This includes all design objects and information related to location and security.

Refer to Table 11-1 for a list of important differences between the two tools.

Table 11-1 Comparison of Snapshots and Metadata Loader

Feature

Snapshots

Metadata Loader

Scope

Captures metadata related to objects in the Project Navigator only. Captures metadata for mappings, process flows, and other design objects. Does not capture information about locations, security, and user defined objects.

Captures all metadata related to a repository including all design objects and information about locations, security, and user defined objects.

Output

You can create a full snapshot from which to restore objects. Or you can create a signature snapshot which requires less space and enables you to track changes but not restore objects. Both types of snapshots are stored in Oracle Database.

When exporting, the Metadata Loader creates a zip file with the extension .mdl.You can use the output to restore a repository or populate a new repository on a different Oracle Database.

Integration with Version Control Tools

You can save the output as a file and then export the file into a version control tool.

You can export MDL files into a version control tool. When using the GUI, first extract the MDL file before putting the objects into the version control system. When using the OMB Plus scripting language, set zipFILEFORMAT=N as described in "About Metadata Loader Control Files".

Compatibility

Snapshots are not compatible between releases of Oracle Warehouse Builder.

MDL files are upwards compatible with newer releases of Oracle Warehouse Builder. When you import an MDL file from a previous release, the utility automatically upgrades the metadata to the new release.

Object Locking

To restore a snapshot, the Change Manager must obtain a lock on all primary objects. Locks held within that session are first freed by prompting the user to save or revert any pending changes, then automatically closing all editor windows. If a lock is held by another session, the restore fails and Change Manager rolls back any changes.

To import, the Metadata Loader must obtain a lock on all the primary objects. If a necessary lock is not available, the import fails and the Metadata Loader rolls back any changes.

Compare

You can compare snapshots by starting a command in the user interface.

You can compare MDL files by using a third-party diff tool.

Using Snapshots

When using snapshots, you can backup and restore your metadata, maintain a history of metadata changes, and compare different versions of the metadata.

A snapshot captures all the metadata information about the selected objects and their relationships at a particular instance of time. While an object can only have one current definition in a workspace, it can have multiple snapshots that describe its changing states throughout its history. Oracle Warehouse Builder supports the following types of snapshots:

- Full snapshots provide backup and restore functionality.

- Signature snapshots provide historical records for comparison.

Snapshots are stored in Oracle Database. Contrast this with Metadata Loader exports, which are stored as separate disk files. You can export snapshots to disk files.

Snapshots are useful for both warehouse managers and designers. Managers can use full snapshots to perform large-scale actions, such as deploying a warehouse or restoring a warehouse to an earlier state. Designers can create full snapshots of a particular component under development so that, if necessary, they can restore that component to its previous state. Designers can also use signature snapshots to track the changes made to a particular component.

When used with other features, such as MDL metadata imports and impact analyses, snapshots help you manage the metadata. For example, you can use snapshots to determine the impact an MDL metadata import has on the current metadata workspace. With the knowledge gained by the comparison, you may choose to import the metadata at a lower level of detail to avoid overwriting the definition of related metadata objects.

Snapshots are also used to support the recycle bin, providing the information necessary to restore a deleted metadata object.

The rest of this section describes the metadata change management feature using the graphical user interface. For information about creating and managing snapshots using scripts, see Oracle Warehouse Builder API and Scripting Reference.

Creating Snapshots

When you take a snapshot, you capture the metadata of all or specific objects in your workspace at a given point in time. You can use a snapshot to detect and report changes in your metadata.

You can create snapshots of any first class objects, except for automatic default objects, and User or Role objects. Use Create Snapshot wizard to create snapshots.

A snapshot of a collection is a snapshot of both the shortcuts in the collection and the actual objects. The same applies to a snapshot of a user folder, because it includes references (which are similar to shortcuts) to both contained and actual objects.

To create a snapshot:

1. In the Project Navigator, select all the objects to include in the snapshot.
You must not select parent or child objects, because the wizard does that for you.

For example, if you select a collection that contains two cubes, then the snapshot includes both cubes and any gives you the option to include any dependent objects such as dimensions and source tables.

You must select actual objects or user folders, not the standard folders that contain them.

2. Right-click the selected object, then select Snapshot, then select New.
Description of the illustration snapshot_01.gif

Alternatively, from the File menu, select Snapshot, then select New.

3. On the Welcome screen, click Next.
You can get supporting information at any time by clicking Help.

Description of the illustration snapshot_02.gif

4. On the Name page, specify the Name and the Type (Full or Signature) of the snapshot.
Click Next.

[Optional] Provide a Description.

Description of the illustration snapshot_03.gif

5. On the Components screen, choose whether to select the Cascade option.
Click Next.

This screen displays the components that are captured in the snapshot. If a component is a node-level object, such as a module, then select the Cascade option to include the subcomponents.

Description of the illustration snapshot_04.gif

6. On the Dependency screen, specify the Depth of dependency to include dependent objects in the snapshot.
Click Next.

Because it impacts performance, avoid specifying unnecessarily large values for depth. For example, supplying a depth value greater than 0 for a Project snapshot searches Globals for dependencies.

Description of the illustration snapshot_05.gif

7. On the Finish screen, review the characteristics of the snapshot.
Click Finish to create the snapshot.

Description of the illustration snapshot_06.gif

8. The system starts creating the snapshot; notice the Create Snapshot Progress pop-up.
Description of the illustration snapshot_07.gif

When the snapshot is complete, an Oracle Warehouse Builder Note screen appears, stating "Snapshot created successfully."

Click OK.

Description of the illustration snapshot_08.gif

Adding Components to a Snapshot

After you create a snapshot, you can add more components. Keep in mind, however, that when you add components, you are changing the historical record provided by the snapshot, so its creation date changes.

To update a snapshot, use the Add to Snapshot wizard.

To add new components to the snapshot:

1. In the Design Center Project Navigator, select all the components you want to add to the snapshot.
For example, you can select tables, mappings, and dimensions from an Oracle module.

2. Right-click and select Snapshot, then select Add to Existing.
Alternatively, from the File menu, select Snapshot, then select Add to Existing.

Description of the illustration snapshot_09.gif

The Add to Snapshot wizard appears.

3. On the Welcome screen, click Next.
You can get supporting information at any time by clicking Help.

Description of the illustration snapshot_10.gif

4. On the Snapshot screen, from the list of snapshots, select the snapshot where to add the components.
Click Next.

Description of the illustration snapshot_11.gif

5. On the Components screen, note all the components that are added to the snapshot. If a component is a folder level object, such as a module, then select the Cascade option to include its subcomponents.
Click Next.

Description of the illustration snapshot_12.gif

6. On the Finish screen, review the characteristics of the snapshot.
Click Finish to update the snapshot.

Description of the illustration snapshot_13.gif

7. The system starts updating the snapshot; notice the Update Snapshot Progress pop-up.
When the snapshot is complete, an Oracle Warehouse Builder Note screen appears, stating "Snapshot updated successfully."

Click OK.

Description of the illustration snapshot_14.gif

Managing Snapshots

You can manage your snapshots from the Metadata Change Management window in the Design Center. To open this window, select Change Manager from the Tools menu.

Description of the illustration change_mgr_01.gif

The Metadata Change Management window contains a menu bar and a toolbar. You can start most tasks in several different ways, either by using the menus, clicking the tools, or right-clicking a snapshot or a component.

Metadata Change Management window supports the following activities:

- "Managing Snapshot Access Privileges"

- "Comparing Snapshots"

- "Restoring Workspace Objects From Snapshots"

- "Exporting and Importing Snapshots"

- "Deleting Snapshots"

Figure 11-1 shows the Metadata Change Management window.

Figure 11-1 Metadata Change Management Window

Description of "Figure 11-1 Metadata Change Management Window"

Managing Snapshot Access Privileges

You can control access to snapshots just like any other object. By default, everyone has full access rights to the snapshots.

To change snapshot access privileges:

1. In the left section of the Metadata Change Management window, right-click the name of the snapshot.

2. From the menu, select Security.
Description of the illustration change_mgr_03.gif

The Snapshot Privilege Management dialog box is displayed.

3. On the Snapshot Privilege Management screen, for each user or role, select the privileges to grant and clear the privileges to deny.
Click Help for additional information.

Description of the illustration change_mgr_04.gif

Comparing Snapshots

You can compare two snapshots, or a snapshot with a current workspace object. The results of a comparison list all objects as one of:

- Identical objects appearing in both snapshots

- An object appearing in only one snapshot

- Similar objects appearing in both snapshots, with different property values

If you take a snapshot of an object that has a child object, and that child object subsequently changes, a comparison shows that the parent object has changed. For example, if you create a Cascade snapshot of a project, all the modules in that project are its children. If any of the modules change, a comparison of the snapshot to the workspace shows that the project has changed.

The Metadata Change Manager uses Universal Object Identifiers (UOIDs) as the basis for all comparisons. When you delete an object and re-create it with the same metadata, the object has a different UOID although it may be identical to the deleted object in all other aspects. When you compare the re-created object to its original version, the results show that all the metadata has changed. Likewise, objects do not match if they have been deleted and re-created during an import or Intelligence Object derivation.

A temporary signature snapshot of the current workspace object is taken automatically; this increases the comparison time. If you are planning to make multiple comparisons to the same current workspace object, Oracle recommends that you take a signature snapshot and use it directly in snapshot-to-snapshot comparisons.

Two compare two snapshots:

1. On the Metadata Change Management screen, select two snapshots for comparison.
Right-click the selected snapshots, and select Compare.

Alternatively, from the Snapshot menu, select Compare.

Description of the illustration change_mgr_05.gif

The Compare Two Snapshots screen appears.

2. On the Compare Two Snapshots screen, ensure that the correct snapshots are selected, and click Compare.
[Optional] Click Help for additional information.

Description of the illustration change_mgr_06.gif

The Snapshot Comparison screen appears.

3. The Snapshot Comparison screen displays the differences between the two snapshots. By selecting changed objects you can see the details of the changes.
Description of the illustration change_mgr_07.gif

If there are no differences between snapshots, an Oracle Warehouse Builder Note screen appears, stating "The two snapshots are identical."

Click OK.

Description of the illustration change_mgr_08.gif

4. [Optional] Click Save As to save the results of the comparison to an *.xml file.

5. Click Close.

To compare the current version of an object with a snapshot version:

1. From the Project Navigator, select the object for comparison.

2. Right-click the selected object, select Snapshot, and then select Compare.
Description of the illustration change_mgr_09.gif

Alternatively, from the File menu, select Snapshot, and then select Compare.

The Choose Snapshot screen appears. It only lists the snapshots that contain the object of interest.

3. On the Choose Snapshot screen, select the snapshot for comparison.
Click OK.

Description of the illustration change_mgr_10.gif

4. The Snapshot Comparison window displays the differences between the two objects. If there are none, then a message informs you that the objects are the same.

5. The Snapshot Comparison screen displays the differences between the object and the snapshot. By selecting changed objects you can see the details of the changes.
Description of the illustration change_mgr_11.gif

If there are no differences between snapshots, an Oracle Warehouse Builder Note screen appears, stating "The object is identical to the snapshot snapshot".

Description of the illustration change_mgr_12.gif

Click OK.

6. [Optional] Click Save As to save the results of the comparison to an *.xml file.

7. Click Close.

Converting a Full Snapshot to a Signature Snapshot

You can convert a full snapshot to a signature snapshot if it is no longer necessary for backup. This conversion preserves the snapshot history while saving a significant amount of space in the workspace.

A signature snapshot cannot be used to restore metadata objects.

To convert a full snapshot:

1. Open the Metadata Change Management window, as described in "Managing Snapshots".

2. Select the snapshot to convert.

3. Right-click the selected snapshot, and select Convert to Signature.
Alternatively, from the Snapshot menu, select Convert to Signature.

Description of the illustration change_mgr_13.gif

4. On Oracle Warehouse Builder Warning dialog box, click Yes.
Description of the illustration change_mgr_14.gif

5. Notice that the Type of the snapshot has changed to Signature.
Description of the illustration change_mgr_15.gif

Restoring Workspace Objects From Snapshots

You can replace the current definition of an object in the workspace with the snapshot image of that object.

- You can only use full snapshots; you cannot restore objects from signature snapshots.

- You can restore all components or only selected components of the snapshot.

- When you restore a collection from a snapshot, you restore both the collection and the actual objects.

- When you restore a container, all its child objects are also restored.

- To restore only the collection or selected objects within a container, use the Components tab.

To restore objects from a snapshot:

1. Save any work that you have done in the current session.

2. Open the Metadata Change Management window, as described in "Managing Snapshots".

3. Select the snapshot that contains the version of the objects you want to restore.

4. [Optional] To restore all objects, right-click the snapshot, and select Restore.
Description of the illustration change_mgr_16.gif

5. [Optional] to restore only some components, select these components in the Components tab, right-click the component, and select Restore.
Description of the illustration change_mgr_17.gif

6. [Optional] If the most recent changes to the object have not been committed, an Oracle Warehouse Builder Warning note appears, stating "You must commit your changes before restoring a snapshot. Do you want to commit now?"
Click Yes.

Description of the illustration change_mgr_18.gif

7. On the Restore Snapshot screen, review the objects in the list and verify that the correct objects are restored. If you
Select Cascade Up. This ensures that any components whose parents no longer exist in the workspace are restored with new parent objects.

Click Restore.

Description of the illustration change_mgr_19.gif

8. An Oracle Warehouse Builder Warning note appears, stating "All currently open editors will be closed after a successful restore. Do you want to continue?"
Click Yes.

Description of the illustration change_mgr_20.gif

9. The system starts restoring the snapshot; notice the Restore Snapshot Progress pop-up.
When the snapshot is restored, an Oracle Warehouse Builder Note screen appears, stating "Snapshot restored successfully."

Click OK.

Description of the illustration change_mgr_21.gif

Exporting and Importing Snapshots

You can export a full snapshot to an MDL file and use this file to re-create metadata objects either in the same database or in a different one. You cannot export signature snapshots or individual components of a snapshot.

To export a snapshot:

1. Open the Metadata Change Management window.

2. Select the full snapshot you want to export.

3. From the Snapshot menu, select Export.
Description of the illustration change_mgr_22.gif

4. [Optional] If the most recent changes to the object have not been committed, an Oracle Warehouse Builder Warning note appears, stating "You must either save or revert your changes before exporting."
Click Save.

Description of the illustration change_mgr_23.gif

5. On the Metadata Export screen, do the following:

- Click Browse to select the location and name of the export file (File Name).

- Click Browse to select the location of the Log File.

- Click Export.

The export file has an .mdl extension, and the log file has a .log extension.

[Optional] Click Help for additional information.

Description of the illustration change_mgr_24.gif

6. The Metadata Export Progress screen appears.
When the progress bar shows 100%, click OK.

Description of the illustration change_mgr_25.gif

To import a snapshot:

1. From the File menu, select Import, then select Warehouse Builder Metadata.
Description of the illustration change_mgr_26.gif

2. On the Metadata Import screen, specify the File Name of the file that is imported.
Click Import.

Description of the illustration change_mgr_27.gif

3. The Metadata Import Progress screen appears.
When the progress bar shows 100%, click OK.

Description of the illustration change_mgr_28.gif

Deleting Snapshots

You can delete snapshots or components within a snapshot from the Metadata Change Management window.

You cannot delete individual components of a signature snapshot.

To delete a snapshot:

1. On the Metadata Change Management screen, select the snapshot to delete.

2. Right-click the snapshot and select Delete.
Alternatively, from the Snapshot menu, select Delete.

Description of the illustration change_mgr_29.gif

3. An Oracle Warehouse Builder Warning note appears, stating "You must either save or revert your changes before exporting."
Click Yes.

Description of the illustration change_mgr_31.gif

To delete components from a snapshot:

1. In the Metadata Change Management, select the snapshot from where to delete components.

2. On the Components tab, select the component to delete, right-click the component, then select Delete.
Alternatively, from the Snapshot menu, select Delete.

Description of the illustration change_mgr_30.gif

Oracle Warehouse Builder displays a delete confirmation dialog box.

3. Oracle Warehouse Builder Warning note appears, stating "Are you sure you want to delete the selected component(s) and all its children?"
Click Yes.

Description of the illustration change_mgr_32.gif

Snapshot Performance

Performance of snapshot operations depends on how accurate the SQL optimizer statistics are for a small subset of tables and indexes. Because most of these in a newly created repository contain little data, it is necessary to seed and lock the statistics initially. This ensures reasonable performance for moderately sized snapshots in a lightly populated repository.

As the number and size of snapshots increases, unless accurate statistics are refreshed on a periodic basis, the performance of snapshots degrades. Although a refresh may be performed in several different ways, OMBOPTIMIZE (in OMB*Plus) or Optimize Repository (in Tools menu) should be run. Otherwise, certain tables remain locked and continue to use old, seeded statistics.

12 Importing, Exporting, and Upgrading Metadata

This section describes how to use the Metadata Loader for change and version management. The Metadata Loader copies and moves all types of metadata objects in a repository. With this utility, you can move metadata between Oracle Warehouse Builder repositories that reside on platforms with different operating systems. You can use the Design Center to run the Metadata Loader utilities. The Design Center provides a graphical interface that guides you through the process of exporting and importing metadata.

This section contains the following topics:

- "Exporting Metadata from the Design Center"

- "Importing Metadata Using the Design Center"

- "Upgrading Metadata from Earlier Releases"

- "Metadata Loader Utilities"

- "Multiple Session Concurrency and MDL"

- "Metadata Loader Log File"

- "About Metadata Loader Results"

- "Managing Versions and History with the Metadata Loader"

Exporting Metadata from the Design Center

You can use Design Center to export objects from a workspace into an MDL file. This includes objects that are part of the Project Navigator, Locations Navigator, and Globals Navigator. The information related to the exported objects, such as table columns and their constraints, data loading configuration parameters, and named attribute sets, are also exported.

Before you attempt to export metadata, ensure you have READ privileges on any object to export. You must have READ privileges on folder objects. If you do not have READ privileges on a folder object, such as projects or modules, the folder object and all objects that it contains are not exported. During an export, the Metadata Export Utility skips objects for which you do not have READ privileges. It logs information about the list of objects that have not been exported due to lack of security privileges. See "Metadata Loader Log File" for details about viewing the list of objects that were not exported.

By default, READ privileges are provided on all the workspace objects to all registered users. See "Export Advanced Options Dialog Box" to export security information such as users, roles, role assignments, and object privileges.

You have two options for exporting metadata. You could either export the entire design or you could export selected objects in the workspace. To export selected objects, then those objects must be within the same navigator. For example, you cannot export a table from the Project Navigator and a public transformation from the Globals Navigator at the same time; you must export them in two separate steps.

Before starting the export operation, take care of the following:

- Ensure the destination computer has sufficient disk storage. If there is insufficient disk space, the export fails. The destination computer must be able to contain the entire metadata file, because the export utility cannot save portions of the metadata file.

- Ensure that you are the only user accessing the objects to be exported. To ensure that you are exporting the most up-to-date metadata, it is advisable to ask all other users to log out of the workspace. See "Multiple Session Concurrency and MDL".

Note:
When you export a code template map that contains a user-defined code template, the code template is not automatically included in the export operation. You must first explicitly import any user-defined code templates the code template mapping to contain.

To export metadata from a workspace using the Design Center:

1. From the Design Center, select the object or objects you want to export.
You can select multiple objects by holding down the Control key and selecting the objects.

You may export individual objects such as tables, or groups of objects. When you export projects nodes, or modules, you also export the objects they contain. When you export collections, you also export the objects they reference.

2. From the File menu, select Export and then Warehouse Builder Metadata.
Description of the illustration exporting_01.gif

3. [Optional] If you made changes to the repository metadata before running the export utility, a warning dialog box is displayed.
Click Save to save changes or Revert to revert to the previously saved version.

Description of the illustration exporting_02.gif

4. In the Metadata Export Dialog Box:

- Click Browse to specify the File Name (name and location) of the export file.

- Click Browse to specify the Log File (name and location).

- [Optional] Under Annotations, enter comments about the export file.

- [Optional] Check Export all object dependencies if you are also exporting all the dependencies of the exported objects.

- [Optional] Click Advanced to export additional metadata. See "Export Advanced Options Dialog Box".

See "Metadata Export Dialog Box".

5. Click Export.

6. When the export completes successfully (see "Metadata Progress Dialog Box"), in the Metadata Export Dialog box, click OK.

Importing Metadata Using the Design Center

You can use the Design Center to import metadata. The Metadata Import Utility also automatically upgrades metadata that was created using an earlier version of Oracle Warehouse Builder to the current version. See "Upgrading Metadata from Earlier Releases" for more information about upgrading metadata.

To prepare for importing metadata, you must take care of the following:

- Required Access Privileges: To import metadata, the user performing the import must have the following privileges:

- EDIT privilege on existing objects that are being replaced by the import.

- CREATE privilege on existing folder objects under which new objects are created by the import.

By default, the FULL_CONTROL privilege is assigned on all workspace objects to registered users. The Metadata Import Utility skips objects for which the user importing metadata does not have the required privileges. The list of objects that have not been imported due to security privileges are logged in the Metadata Loader Log File. See "Metadata Loader Log File"

You can import security information such as users and roles. When importing user metadata, if a corresponding database user does not exist for a user, the import fails and an error message is entered to the Metadata Loader Log File. See "Import Advanced Options Dialog Box" for information about importing security information such as users and roles, and "Metadata Loader Log File".

Because the Metadata Import Utility alters the repository, the metadata objects must be locked before importing. See "Multiple Session Concurrency and MDL".

- Backup of Current Workspace: Consider making a backup of your existing workspace, either in the form of an export or a metadata snapshot, before attempting a large or complex import.

- Multiple Language Support Base Language Compatibility: The base language is the default language used in the repository and is set using the Repository Assistant during installation. You cannot alter this setting after installing the repository. See "Languages" for more information about setting the base language in a repository.

Importing Objects

To import objects from an export file using the Design Center:

1. From the Design Center, select File, select Import, and then select Warehouse Builder Metadata.
Description of the illustration importing_01.gif

2. [Optional] If you had made changes to the repository metadata before running the import utility, a warning dialog box is displayed.
Click Save to save changes or Revert to revert to the previously saved version.

Description of the illustration importing_02.gif

3. In the Metadata Import dialog box:

- Click Browse to specify the File Name (name and location) of the import file.

- Click Browse to specify the Log File (name and location).

- Under Object Selection, choose either Import all objects from file or Import selected objects from file.

- Under Import Option, select one of Create new metadata only, Update metadata replace existing objects and create new metadata, Merge metadata merge existing objects and create new metadata, or Replace existing objects only.

- Under Match by, select one of Universal Identifier or Names.

- [Optional] Click Show Summary to view a summary of the contents of the export file. See "File Summary Dialog Box".

- [Optional] Click Advanced to import metadata for additional languages, security information, or user-defined properties. See "Import Advanced Options Dialog Box".

See "Metadata Import Dialog Box".

4. Click Import.

5. The Metadata Import Progress dialog box is displayed; it indicates the progress of the import. You can cancel an in-progress Metadata Import by clicking Cancel. See "Metadata Progress Dialog Box".

If the MDL file that you selected for import was created using an earlier version of Oracle Warehouse Builder, clicking Show Summary, Advanced, or Import displays the Metadata Upgrade dialog box. This dialog box enables you to automatically upgrade the selected MDL file to the current version of Oracle Warehouse Builder. For more information about this dialog, see "Metadata Upgrade Dialog Box".

Combining Import Modes and Matching Criteria

Each search method used as matching criteria may be combined with an import mode. Each combination offers different results in the import process. The mode that you select determines how the metadata import utility searches for metadata objects in the workspace, before importing.

For example, if the search is of a repository object in the export file, the Metadata Import Utility searches the workspace for the object's name. If an object with the corresponding name is not found, the resulting actions are based on the import mode you select.

Table 12-1 describes what happens in the available import modes for repository objects that either match or do not match the object names.

Table 12-1 Import Mode Results

Import Mode

Result Using Matching Names

Result Not Using Matching Names

Create Mode

A message is written to the log file that the object exists, and the object is skipped.

A new object is created.

Replace Mode

The object is replaced.

A warning message is written to the log file that the object cannot be replaced because it does not exist in the workspace. The object is skipped.

Update Mode

The object is replaced.

A new object is created.

Merge Mode

The object is merged.

A new object is created.

The MDL reads and processes the imported metadata and writes status and diagnostic information in the log file.

Import Different Base Languages

When you import metadata in multiple languages, the language settings in the target repository may be different from the language settings in the export file. For example, the target repository may have the base language as English and additional language as French and German. But the export file may have the base language as French and additional language as English and German. This section describes how the MDL handles these conditions.

Different Base Languages in the Import File and Target Repository

When you import metadata, MDL compares the ISO identification of the base language in the import file with the ISO identification of the base language of the target repository. The ISO identification consists of the language ID followed by the locale, in the format language_locale. For example, en_US is American English and fr_FR is French.

If the base ISO identification languages are different, MDL displays a warning dialog box informing you that the base languages are different and warns you that Oracle recommends that you import metadata with the same character set and base language. You have the option to continue with the import. Click Yes to continue with the import. Click No to cancel the import.

Under certain circumstances, continuing to import metadata when the base languages are different may lead to corruption of the metadata being imported. Oracle recommends that you move metadata between repositories with the same character set and base languages.

If the base ISO identification languages are the same, but the locales are different, the Metadata Import Utility displays a warning dialog box to determine whether you want to continue with the import. For example, the export file contains English and the base language of the repository is American English. Click Yes to import metadata, or click No to cancel the import.

Importing Supported Languages

During the import, MDL checks if the additional languages in the import file exist in the target repository. If the import file contains additional languages that do not exist in the target repository, and you specify that these additional languages are to be imported, the Metadata Import utility writes a warning message in the MDL log file stating that the additional languages are not installed in the repository.

Import Validation Rules

When you import a set of definitions from previously exported metadata, the import utility updates existing definitions within a project. However, certain metadata definitions require attention to ensure that they are updated correctly. The following are examples of some errors you may see:

- Mapping Definitions. The Metadata Import Utility binds imported mapping operators to their physical objects if the associated objects exist in the workspace. However, if the associated physical objects do not exist in the workspace, the imported mapping operators are not bound. The Metadata Import Utility writes a warning message in the log file, which states that the mapping operators are not bound. You must then synchronize the new mapping operators with the physical objects they represent.

- Foreign Key Definitions. It is possible that a source MDL file contains foreign key references to unique or primary keys that are not in the target workspace. If the referenced unique or primary keys for any foreign key appearing in the MDL file do not exist in the target workspace, the MDL Import Utility writes a warning message in the log file, which states that the workspace does not contain a referenced key for the foreign key.

Upgrading Metadata from Earlier Releases

While importing metadata, the Metadata Import Utility automatically upgrades metadata created using earlier releases to Oracle Warehouse Builder 11g Release 2 (11.2). You do not have to manually upgrade the metadata from a previous release of Oracle Warehouse Builder.

When you import an MDL file, the version used to create the file is automatically detected. If the MDL file was created using an earlier release of Oracle Warehouse Builder, the Metadata Upgrade dialog box is displayed. This dialog box enables you to upgrade the MDL file to the current version. See "Metadata Upgrade Dialog Box".

If you import an .mdl file that contains metadata for gateway modules (such as DB2 or Informix) from an older version of Oracle Warehouse Builder, the file may not import the metadata into the corresponding source module folders of a project. These imported files are stored under the Others node in the Project Navigator. You must manually copy the metadata for the gateway modules into the correct source module folders.

The production versions of Oracle Warehouse Builder from which metadata is automatically upgraded to Oracle Warehouse Builder 11g Release 2 (11.2) are as follows:

- Oracle Warehouse Builder 9.2

- Oracle Warehouse Builder 10g Release 1

- Oracle Warehouse Builder 10g Release 2

- Oracle Warehouse Builder 11g Release 1

If you must upgrade an MDL file from an older version of Oracle Warehouse Builder, you must first upgrade it to one of Oracle Warehouse Builder 9.2, 10.1, 10.2, or 11.1, and then upgrade this intermediate MDL file to Oracle Warehouse Builder 11.2.

Note:
Before importing the MDL file, you must stop the Control Center by running the script OWB_HOME/owb/rtp/sql/stop_service.sql.

Changes to Workspace Objects When Upgrading from Oracle Warehouse Builder 9.2

When you upgrade from Oracle Warehouse Builder 9.2, the upgrade utility makes the following changes to objects in the workspace:

- Dimension and Cube Mapping Operators: The mapping operators for dimensions and cubes are converted to table operators. These table operators use the physical tables created by the MDL Upgrade Utility for dimensions and cubes.

- Dimensions: An associated dimension table is created with the same name as the dimension. The table contains the columns, constraints, and attribute sets defined in the Dimension Editor Table Properties of the dimension in the previous release.

- Mapping Display Sets for Dimension Hierarchies: Any mapping sets created based on the named attribute set for a dimension hierarchy are removed. This is because display sets for dimension hierarchies are no longer automatically created and maintained.

- Dimension Attributes: For each level attribute upgraded, a dimension attribute with the same name is created, if it does not exist in the dimension.

- Cubes: An associated cube table is created with the same name as the cube. The cube table contains columns, constraints, and attribute sets defined in the Cube Editor Table Properties of the cube in the previous release.

- Intelligence Objects and Reports: In the previous release, intelligence objects and reports were available only using OMB Plus scripting. These objects are not upgraded.

- Locations and Control Center Connections: Locations and Control Center connections are moved out of the projects that own them so that they can be shared across the entire workspace. Thus the statistics in the import log file displays an additional project for these objects.

- Control Centers and Locations: After an upgrade, there is no association between the locations and the control centers that they reference. You must review the control center details using the Edit Control Center dialog box and select the locations associated with this control center.

- Advanced Queues: An associated queue table is created based on the property AQ queue table name. The queue table created by the MDL File Upgrade Utility contains a column whose data type is the object type for that advanced queue.

- Advanced Queue Operator in a Mapping: Mapping Advanced Queue operators are changed to contain only one attribute called PAYLOAD. For Mapping Advanced Queue operators that are used as a source, a new Expand operator is added after the Mapping Advanced Queue operator. For Mapping Advanced Queue operators that are used as a target, a new Construct operator is added before the Mapping Advanced Queue operator.

- Mapping Operator Names: The MDL Upgrade Utility ensures that the physical names and business names of all mapping operators are unique.

Changes to Workspace Objects When Upgrading from Oracle Warehouse Builder 10.1, 10.2 or 11.1

When you upgrade from Oracle Warehouse Builder 10.1, 10.2, or 11.1 to Oracle Warehouse Builder 11.2, the upgrade utility makes the following changes to objects in the workspace:

- Mapping Table Function Operators: The mapping operators for table functions are upgraded to have only one input group and one output group. Old input groups that were configured as a REF cursor type are upgraded to a SYS_REFCURSOR type, and a new construct operator is added to the map; its input group values are the same as in the REF cursor type input group, and the output group attribute is set to SYS_RECURSOR type.

- Mapping Key Lookup Operators: The mapping operators for key lookups are upgraded to the new lookup operator.

- Stream Capture Process Objects: Stream capture process objects are not upgraded.

- Business Presentation Modules: Business presentation modules and their contents are not upgraded.

- BI Beans Locations: BI beans locations are not upgraded.

Checking for Warnings and Error Messages

After upgrading the metadata, check the log file for warnings and errors.

- If you receive warnings during the upgrade, the upgrade utility completes and logs the warnings. If you receive errors, the upgrade utility terminates and logs the errors.

- If warnings and errors are shown after an upgrade, search for the words Warning and Error in the log file to determine the problem.

- If an unexpected error occurs and the upgrade terminates, the log file contains the details. Check your log file or contact Oracle Support.

Design Center Metadata Management Dialog Boxes

The Design Center uses several dialogs to manage metadata export, import, and upgrade. These are:

Metadata Export Dialog Box

The Metadata Export dialog box displays the names and the types of the exported objects.

Description of the illustration exporting_03.gif

The Metadata Export dialog box also contains the following items:

- Annotations: Use this field to enter any comments about the file that contains the exported objects.

- File Name: Displays a default path and file name for the export file. You can retain this default or specify a directory and file name. Type the name of the export file to create or click Browse to locate a directory or file. The file name extension commonly used is .mdl.

- Log File: Use this field to specify the file name and path for the log file that stores diagnostic and statistical information about the export. See "Metadata Loader Log File"

- Export all object dependencies: Select this option to export all the dependencies of the objects being exported. For example, when you export a table, the location to which the table is deployed is also exported.
Public objects such as locations, public transformations, public experts, public icon sets, or public data rules belong to a project called PUBLIC_PROJECT. You can export the PUBLIC_PROJECT and its objects if the selected exported objects have a dependency on the public objects and if you select the Export all object dependencies option.

- Advanced: Use the Advanced button to export additional metadata such as user-defined properties, security information, and additional languages. See "Export Advanced Options Dialog Box".

Click Export to export the metadata for the selected objects. The Metadata Export Progress dialog box is displayed. See "Metadata Export Dialog Box" for more information about the contents of this dialog box.

Export Advanced Options Dialog Box

Use the Export Advanced Options dialog box to export any of the following:

- Additional language metadata

- User-defined definitions

- Security information

Description of the illustration exporting_04.gif

This dialog box contains two sections: Languages and Administration.

Languages

The Base Language field displays the base language of the repository. Oracle Warehouse Builder exports and imports data in the base language.

You can specify additional languages to export and import objects that contain translations for their business names and descriptions. The Available Languages list displays the list of languages that are installed in the repository. To export or import additional languages, select the language and click the arrows to move the language from the Available Languages list to the Selected Languages list. You may choose multiple languages at the same time by holding down the Control or Shift key while making your selection.

The Available Languages list contains language entries only if you installed additional languages in the repository. For example, the repository has American English as base language, and additional languages French and Simplified Chinese. While exporting metadata from the repository, you may select French as the additional language. The Metadata Export Utility then exports the base language of the object, American English, and the additional language French for objects that contain a French translation. Additional languages are exported for an object only if they contain translations for the business names and descriptions.

Administration

You may export additional metadata if you have administrator privileges. The options you may choose to export additional metadata are as follows:

- Export user-defined definition: Select this option to export the definitions of user-defined objects and user-defined properties.

- Export security information: Select this option to include security information such as object privileges or role assignments made to users. See Chapter 13, "Managing Security" for more information about security.

After you specify the options on the Export Advanced Options dialog box, click OK to close this dialog box and return to the Metadata Export dialog box.

Metadata Import Dialog Box

Use the Metadata Import dialog box to specify the information required to import metadata in an export file.

Description of the illustration importing_03.gif

Specify the following information on this dialog box:

- File Name: Type the name of the MDL file or click Browse to locate the MDL file you want to import.

- Log File: Type the name of the log file, along with the path, that stores diagnostic and statistical information about the import. You can also click Browse to locate the log file. See "Metadata Loader Log File" for more information about log files.

- Object Selection: The Metadata Import Utility enables you to select the objects to import from the MDL file. The Object Selection section contains the following options:

- Import all objects from file: Select this option to import all objects contained in the export file.

- Import selected objects from file: Select this option to import only some objects contained in the MDL file. Click Select Objects to select the objects to import. The Import Object Selection dialog box is displayed.
The Import Object Selection dialog box is displayed contains two sections: Available and Selected. The Available section contains primary objects such as projects, modules, tables, views, and connections, which are specified in the MDL file. Expand the nodes in this section to view the objects they contain. When you select a node, all the objects that it contains are included in the import. For example, if you select a module node, all the objects contained in the module are imported. Use the shuttle buttons to move the selected objects from the Available section to the Selected section.

The MDL file that is imported may also contain administrative objects. To import these administrative objects, you must have administrative privileges. If these privileges are absent, the following occurs:

- The Available section of the Import Object Selection Page dialog box does not display any administrative objects that the MDL file may contain.

- The Import Utility displays an alert that the user does not have the required administrative privileges to perform the import, provided the MDL file contains only administrative objects.

- Import Option: Use the Import Option section to select the import mode. You can select the following options for the import mode:

- Create new metadata only: This option, known as create mode, adds new objects to a workspace.

- Update metadata (replace existing objects and create new metadata): This option, known as update mode, adds new objects to a workspace and also replaces existing objects with those in the MDL file that is imported.

- Merge metadata (merge existing objects and create new metadata): When you select this option, known as merge mode, the MDL adds new objects and overwrites existing objects in the workspace only if they differ from those in the MDL file. The merge mode does not delete existing objects. You cannot import metadata using the merge mode for mappings, pluggable mappings, and data auditors.

- Replace existing objects only: This option, known as replace mode, replaces existing objects in your workspace but does not add new objects. In this mode, the Metadata Import Utility overwrites any existing metadata.

When you import metadata using the update or the replace modes, the import completely replaces the child objects of existing objects, so that the final object equals the source object. Any existing children of a repository object that are not replaced or added are deleted. This occurs regardless of whether a child object occurs in a mapping or is a foreign, primary, or unique key column in a table or view.

For example, in the MDL export file, the CUST table contains three columns with the physical names: last_name, first_name, and middle_init. In the workspace, the same table exists, and contains four columns with the physical names: last_name, first_name, status, and license_ID. During a replace operation, the columns last_name and first_name are replaced, column middle_init is added, and column status and license_ID are deleted. The final result is that the CUST table in the workspace contains the same metadata from the CUST table in the export file.

Using the replace and update modes may cause loss of data constraints, metadata physical property settings, data loading properties, and mapping attribute connections. If you choose to use replace or update modes, ensure that you have the option of restoring the workspace from a backup.

- Match By: When you use the metadata import utility, it first searches the workspace for metadata objects that exist in the workspace and compares them to those in the import file. To compare metadata in the import file with the existing workspace metadata, it uses the matching criteria. How the comparison is made is determined by the import mode and by the chosen search method.
The Match By section provides the following options for matching criteria. By default, the import utility searches by UOIDs. MDL import does not support merging existing mappings.

- Universal Identifier option searches the workspace using the Universal Object Identifiers (UOIDs) of the objects that are imported. The Metadata Import Utility uses the UOIDs to determine whether an object must be created, replaced, or merged during the import operation. Use this method to maintain UOIDs across different workspaces even when object names in the target workspace have changed.

- Names option searches the workspace using the names of the objects that are imported. Physical names are exported to the export file; the physical name determines whether an object must be created, replaced, or merged during an import operation. Use this method to create new UOIDs for those objects when object names in the target schema change.

Import Advanced Options Dialog Box

Use the Import Advanced Options dialog box to import any of the following:

- Additional language metadata

- User-defined definitions

- Security information

Description of the illustration importing_04.gif

This dialog box contains two sections: "Languages" and "Administration".

Languages

The Base Language displays the base language of the repository. By default, data is imported in the base language.

You can specify additional languages to import. The Metadata Import Utility imports the translations of the object for business name and description. The Available Languages list displays the list of languages that are specified in the MDL file. For example, the MDL file contains the additional languages French and Simplified Chinese, but your repository contains only French as the additional language. Then the Available Languages list displays only French. Select the language you want to import and click the arrow to move the language to the Selected Languages list. See "Import Different Base Languages".

Administration

This option is available only if you have administrator privileges and the metadata exists in the MDL file used for import. The options you may choose to import additional metadata are as follows:

- User-defined definitions: To import the definitions for the user-defined objects and the user-defined properties, select the Import User-defined definitions option.

- Security Grants: Select Import security information to import security information such as object privileges and role assignments made to users.

If the MDL file contains any of these objects, then you can import this additional metadata.

When you import an MDL file into a new workspace, to inherit the security information from the old workspace, you must import the security information before you import other objects. To do this you must connect to the workspace as a user with administrator privileges.

After you make your selections on the Import Advanced Options dialog box, click OK to save your selections and return to the Metadata Import dialog box.

Name Conflicts

Name conflicts may occur in the following cases:

- A different object with the same name exists in the target workspace.

- A different object with the same business name exists in the target workspace.

- A different object with the same UOID exists in the workspace.

When a name conflict occurs, the MDL reports an error and terminates the import.

File Summary Dialog Box

The File Summary dialog box contains a brief summary of the contents of the export file. The information on this page is divided into the following sections:

- File section contains the name of the data file, the creation timestamp, the name of the export user, the workspace connection information, the version of the Design Center used for the export, and annotations.

- Administration section contains information about the users and roles. It also lists the following details:

- Base language of the export file

- Additional languages in the export file

- Whether security information were included in the export file

- Whether user-defined definitions were included in the export file

- Statistics section contains details about the types of objects contained in the export file and the number of objects of each type.

Metadata Upgrade Dialog Box

This dialog box is displayed automatically when it is determined that the MDL file being imported was created using a previous version. Use the File Name field to specify the name of the file that stores the upgraded MDL file. You can also click Browse to locate a directory or MDL file.

Click Upgrade to upgrade the MDL file to the current version. After the Upgrade completes, the Metadata Upgrade dialog box is closed. Click Cancel if you do not want to upgrade the MDL file.

Metadata Progress Dialog Box

The Metadata Progress dialog box is titled either Metadata Export Progress, Metadata Import Progress, or Metadata Upgrade Progress. It displays a progress bar that indicates the relative completeness (as a percentage) of the metadata export, import, or upgrade activity. If the operation is successful, a message indicating this displays above the progress bar; it may also display that an error occurred.

Description of the illustration exporting_05.gif

To view detailed information about the metadata export or import, click Show Details. The message log is displayed. The message log contains the following information:

- Start time of the export or import

- Names and types of objects exported or imported

- Warning or error messages

- End time of the export or import

- Location of the export or import log file

- Total export or import time in hh:mi:ss or milliseconds

You can hide the message log by clicking Hide Details.

To view details about the exported or imported objects, click Show Statistics. The Metadata Results dialog is displayed. See "About Metadata Loader Results".

You can cancel an in-progress Metadata Export or Import by clicking Cancel.

After the export or import completes, click OK in the Metadata Progress dialog.

Metadata Loader Utilities

The Metadata Loader consists of the following two utilities:

- Metadata Export Utility
Use the Metadata Export Utility to export metadata from a workspace.

- Metadata Import Utility
Use the Metadata Import Utility to import metadata into a workspace.

MDL uses its own format, and the Metadata Import Utility only reads files of MDL format (files created by the Metadata Export utility). The Metadata Loader file is a formatted zip file.

Metadata Export Utility

The Metadata Export Utility extracts metadata objects from a workspace and writes the information into a zip format file. This zip file has an .mdl extension and contains the following files:

- Metadata Loader XML file: This file contains the objects extracted from the workspace and formatted in XML. It has the same name as the name of the zip file, but with the extension .mdx.

- Catalog: The catalog file is called mdlcatalog.xml and it contains internal information about the Metadata Loader XML file.

The Metadata Export Utility enables you to specify a file name and a path for the exported MDL file. For example, you export the repository metadata into a file called sales.mdl. When you unzip this MDL zip file, you obtain two files. The file sales.mdx contains the repository objects. The file mdlcatalog.xml contains internal information about the MDL XML file.

You can export an entire project, collections, public objects, locations, or any subset of objects. If you export a subset of objects, the MDL exports definitions for each object that you have selected and the parent objects to which the subset belongs. It enables the MDL to maintain the tree relationships for those objects during metadata import.

For example, if you export a single dimension, the export file contains definitions for the dimension, the module to which the dimension belongs, the project to which the module belongs, and the configurations for the dimension.

If you are exporting a subset of objects, ensure that you both export and import all referenced object. You may export the objects referenced by a set of objects by selecting the Export All Dependencies option on the Metadata Export dialog box. For example, if you export a table EMPLOYEES and it contains a foreign key reference to the table DEPARTMENTS, you may choose to export both tables.

Metadata Import Utility

The Metadata Import Utility reads the metadata information from an exported MDL file and creates, replaces, or merges the metadata objects into a workspace. It imports information that belongs to exported metadata objects, such as table columns and their constraints, data loading configuration parameters, and named attribute sets. The Metadata Import Utility enables you to import repository objects even if the references for those objects cannot be satisfied.

You can use the Metadata Import Utility to import objects into a project or a collection. The Metadata Import Utility only reads files created by the metadata export utility.

If the MDL file being imported was created using an earlier product version, the Metadata Import Utility automatically upgrades it to the current version.

See Also:
"Upgrading Metadata from Earlier Releases" for more information about the automatic upgrade of MDL files

Multiple Session Concurrency and MDL

The repository allows multiple clients to access the same workspace concurrently. Oracle Warehouse Builder uses locks to enable only one client to change repository objects. While an object is locked, other clients can only view it in the state it existed after the last transaction instigated by any user is committed.

When replacing or merging objects, the MDL acquires locks on the primary objects that exist both in the repository and in the MDL file. Primary objects include, but are not limited to, projects, modules, tables, dimensions, cubes, mappings, views, and flat files. Secondary objects, such as columns and mapping attributes, are not locked. If locks cannot be obtained because other users are locking the primary objects, then the import fails. Therefore, you must be able to hold locks for primary objects that you are importing. To ensure a successful metadata import, you must be the sole client accessing the workspace.

The MDL saves changes made to the workspace after a successful metadata import (any import with no error messages, including imports with only information or warning messages). The MDL also executes a rollback after an unsuccessful import.

Metadata Loader Log File

Whenever you export or import repository metadata, the MDL writes diagnostic and statistical information to a log file. You can specify the location of the log file when you call the MDL.

The log file enables you to monitor and troubleshoot export and import activities in detail and contains the following information:

- Name of the data file

- Start time and end time of the export or import

- Time taken for the export or import in hours, minutes, and seconds (in hh:mi:ss format) or milliseconds

- Object types exported or imported

- Number of objects of each object type exported or imported
The import log file also displays the total number of objects that have been added, replaced, skipped, and deleted.

- Status messages
Status messages provide information about the import or export process. They are of the following types:

- Informational: Provides information about the import or export, such as missing metadata objects, whether objects were imported, and any reasons why objects were not imported or exported.

- Warning: Cautions you about the import or export of an object but does not indicate a failed or terminated export or import. A warning notifies you of the possibility of unexpected results that could occur because of the export or import.

- Error: Indicates that the MDL export or import was terminated and did not complete successfully. The error message provides a brief description of the reason for the failure.

About Metadata Loader Results

When you use the Metadata Loader Export or Import utilities, you can view the results of a successful export or import task. Use the Metadata Export Results dialog box or the Metadata Import Results dialog box to ensure that all of the objects were exported or imported. To view the results dialog box, click Show Details on the Metadata Export Progress dialog box or the Metadata Import Progress dialog box. This displays the Message Log. Click Show Statistics after this log.

The results dialog box contains the following information:

- The name of the project exported or imported (if applicable).

- The number of objects of each type exported or imported.

- The number of objects of each object type skipped.
Details about the number of skipped objects is displayed only when you import metadata.

Managing Versions and History with the Metadata Loader

Using the Metadata Loader (MDL) utility, you can import and export metadata from any object in the Projects Navigator, Globals Navigator, and Connection Navigator. You can then move exported files into a third-party version control tool such as Oracle Repository, ClearCase, or SourceSafe. You can enter annotations for your MDL export file to keep track of the information contained in the file.

The Metadata Loader (MDL) enables you to populate a new repository and transfer, update, or restore a backup of existing repository metadata. You can copy or move metadata objects between repositories, even if those repositories reside on platforms with different operating systems.

Accessing the Metadata Loader

You can access the Metadata Loader using either the graphical user interface described in this section or using the OMB Plus scripting language described in Oracle Warehouse Builder API and Scripting Reference.

While the graphical interface guides you through the most commonly performed export and import tasks, the OMB Plus scripting language enables you to perform more specialized export and import tasks and enables you to manage a control file.

About Metadata Loader Control Files

When you use the OMB Plus commands related to the Metadata Loader, a control file provides you with greater control over how objects are imported or exported. For example, by default, the Metadata Loader exports objects into a binary zip format. To override the default of exporting to a zip file, use OMBEXPORT MDL_FILE with the CONTROL_FILE option with a control file that contains the option ZIPFILEFORMAT=N.

See Oracle Warehouse Builder API and Scripting Reference for more information about using a control file, the Metadata Loader, and information about each of the following commands:

- OMBIMPORT

- OMBEXPORT

- OMUIMPORT

- OMUIMPORT MDL_FILE

- OMBIMPORT MDL_FILE

- OMUEXPORT MDL_FILE

- OMBEXPORT MDL_FILE

13 Managing Security

This section describes how to implement security options for Oracle Warehouse Builder API and Scripting Reference.

This section includes the following topics:

- "About Metadata Security"

- "Evaluating Metadata Security Strategies"

- "Registering Database Users"

- "Editing User Profiles"

- "Support for a Multiple-user Environment"

- "Defining Security Roles"

- "Editing Role Profiles"

- "Applying Security Properties on Specific Metadata Objects"

- "Security Enforcement"

- "Managing Passwords in Oracle Warehouse Builder"

About Metadata Security

Oracle Warehouse Builder enables you to define security on the metadata stored in the design repository. Oracle Warehouse Builder metadata security operates with Oracle Database security, with Oracle Database provides security for data, while Oracle Warehouse Builder provides security for the metadata.

In addition to being registered in the repository, all users must also be database users in the design repository database. Database users may access the data in the database by using SQL*Plus, but they cannot have access to Oracle Warehouse Builder and its metadata unless they are also registered in Oracle Warehouse Builder.

Metadata security is both optional and flexible. You may choose not to apply any metadata security controls, or define a metadata security policy. You have the option to define multiple users, and apply either full security control or none. You may also implement a custom security strategy based on the security service. After you define a custom security strategy, you may adapt it over time to be more or less restrictive.

The topics in this section describe how to implement metadata security using the Design Center. You may also implement security through OMB Plus. For more information, refer to the Oracle Warehouse Builder API and Scripting Guide.

About the Security Service

Only users with administrative privileges can access the security service under Globals Navigator to manage users and roles of the security policy in Oracle Warehouse Builder API and Scripting Reference.

When you install Oracle Warehouse Builder and then use the Repository Assistant to create a design repository, Oracle Warehouse Builder makes the design repository owner the default administrator. The first time you start the Design Center after installation, you must log in as the design repository owner. You can then define additional administrators or other users as necessary.

When you log in to the Oracle Warehouse Builder Design Center as the design repository owner, it displays the Globals Navigator.

Description of the illustration globals_navigator.gif

To view default security settings:

1. In Globals Navigator, expand Security.

2. Expand Users, and then expand Roles.
Description of the illustration security_01.gif

3. Notice that there are two predefined roles, ADMINISTRATOR and EVERYONE.

4. The one predefined user is the design repository owner; it is assigned the ADMINISTRATOR role by default.
To view or edit the details for a user, in the globals Navigator, under Security and then under Users, select that and double-click the user. The Edit User screen appears.

Description of the illustration security_02.gif

For a complete list of all the tasks administrators can perform, see "Administrator Role".

Evaluating Metadata Security Strategies

Oracle Warehouse Builder enables you to design a metadata security strategy that fits your implementation requirements. As you define your metadata security strategy, recognize that more restrictive policies are more time consuming to implement and maintain.

Consider modeling your strategy based on any of the following security strategies:

- "Minimal Metadata Security Strategy (Default)"

- "Multiuser Security Strategy"

- "Full Metadata Security Strategy"

Minimal Metadata Security Strategy (Default)

Minimal metadata security is the default security policy when you create a new design repository. As your project requirements change over time, you may apply other metadata security strategies. For example, you may not need extra metadata security if you are implementing an internal pilot project, or if you anticipate only few trusted users.

In the case of a minimal metadata security strategy, all users may log in to Oracle Warehouse Builder with the same user name and password, that of the design repository owner. Oracle Database security policies keep the data in the design repository secure, and the metadata is available to anyone who knows the design repository owner logon information. All users can create, edit, and delete all objects.

Multiuser Security Strategy

If your implementation has multiple users and you want to track who performs what operations, implement a multiuser security strategy. This strategy restricts to a single user the rights and access granted to the design repository owner. Although this strategy does not restrict user access to metadata objects, you can apply restrictions at a later date.

To implement security for multiple users:

Log on to Oracle Warehouse Builder as an administrator and complete the instructions in the following sections:

1. "Registering Database Users"

2. "Editing User Profiles"

Full Metadata Security Strategy

This section describes a process for applying all the metadata security options available in Oracle Warehouse Builder. You can enable all or some of these options. For instance, you could take steps one through three but ignore the remaining steps.

Be sure to edit the security properties for all projects in the Project Navigator. By default, the EVERYONE role has FULL_CONTROL object privileges. To change, select the project and then, from the View menu, select Security. Edit the privileges to the EVERYONE role to be more restrictive, and then press Propagate Security Settings icon on the upper left corner. This action applies the new restrictions to all children of this project. For newly created projects and other objects, use the default object privilege setting of Oracle Warehouse Builder API and Scripting Reference users to define access privileges.

To implement full metadata security for multiple users:

Log in to Oracle Warehouse Builder as an administrator and complete the instructions in the following sections:

1. Set the parameter Default Metadata Security Policy to maximum.
In the Design Center select Tools, Preferences, expand Oracle Warehouse Builder, and then select Security Parameters.

2. "Registering Database Users"

3. "Editing User Profiles"
The Default Metadata Security Policy you set in step one of these instructions is not retroactive. It applies only to users you register after changing the setting. You must manually edit the profiles of preexisting users.

4. "Defining Security Roles"

5. "Editing User Profiles"

6. "Applying Security Properties on Specific Metadata Objects"

Registering Database Users

All Oracle Warehouse Builder users must also be Oracle Database users.

You can create new Oracle Warehouse Builder users in one of two ways:

- Use Oracle Warehouse Builder to register existing database users, or to create new ones.
You must have the database CREATE USER privilege to create a user.

- Create new database users and then register them in Oracle Warehouse Builder.
It is possible to create users in SQL Plus, Oracle recommends that you create users through the Oracle Warehouse Builder interface. This ensures that users are assigned all necessary roles and privileges.

For security reasons, you cannot register database administrator users, for example SYS. Also, the database default role settings must not be set to ALL. Oracle Warehouse Builder automatically sets the "database default role setting" for new users. You may change the database default role settings as described in "Changing Database Default Roles".

Note:
Oracle Warehouse Builder user name can be alpha, alpha-numeric or all numeric characters.

Registering Existing Database Users

This section explains how to register existing database users.

To register existing database users:

1. In the Globals Navigator, under Security, right-click Users and select New User.
Description of the illustration new_user_01.gif

The Create User: Welcome screen appears.

2. On the Create User Welcome screen, click Next.
Description of the illustration new_user_02.gif

3. On the Select DB user to register screen, under Available DB Users, select the user or users you want to register, and click the appropriate transfer icon to add the user or users to the Selected Users list.
Click Next.

Description of the illustration new_user_03.gif

4. On the Check to create a location screen, check Create option next to the user you are registering.
Click Next.

Description of the illustration new_user_04.gif

5. On the Summary screen, review the new user definition.
Click Finish.

Description of the illustration new_user_05.gif

6. The Register Users Progress appears. It disappears when registration is complete.
Description of the illustration new_user_06.gif

7. Your new user is now listed under Users.
Description of the illustration new_user_07.gif

Creating New Oracle Database Users

This section explains how to create new database users. You must have the database system privilege CREATE USER.

To create a database user:

1. In the Globals Navigator, under Security, right-click Users and select New User.
Description of the illustration new_user_01.gif

The Create User: Welcome screen appears.

2. On the Create User Welcome screen, click Next.
Description of the illustration new_user_02.gif

3. On the Select DB user to register screen, click Create DB User.
Description of the illustration new_user_08.gif

4. On the Create Database User screen, enter the DBA password, and the Name and Password (with confirmation) of the new user.
Click OK.

You must specify a valid user name and password, and adhere to the security standard implemented on the Oracle Database. For more information about user names, passwords, and password complexity verification routines, refer to Oracle Database Security Guide.

Description of the illustration new_user_09.gif

5. On the Select DB user to register screen, the new user is automatically added to the Selected Users list.
Click Next.

Description of the illustration new_user_10.gif

6. On the Check to create a location screen, check Create option next to the user you are registering.
Click Next.

Description of the illustration new_user_11.gif

7. On the Summary screen, review the new user definition.
Click Finish.

Description of the illustration new_user_12.gif

8. The Register Users Progress appears. It disappears when registration is complete.
Description of the illustration new_user_06.gif

9. Your new user is now listed under Users.
Description of the illustration new_user_13.gif

Changing Database Default Roles

For security reasons, you cannot register database users that have ALL default roles in the database. However, it is possible to change, default setting by correcting the role assignment. There are two options: "Fix Now" and "Fix Later".

Fix Now

If you select the Fix Now option, type the user name and password with SYSDBA privileges. The user is registered, and the necessary commands are issued.

For example, when you register new users, the database role OWB_repository_name is assigned to each user. For security reasons, this role must not be the default role of any registered user. If you attempt to register a user under these conditions and then select Fix Now, the user is registered and the following command is issued:

alter user username default role all except OWB$CLIENT

Fix Later

If you select the Fix Later option, the user is not registered. You must manually change the default role setting in the database using SQL, and then register the user in Oracle Warehouse Builder. To manually change the setting, connect to the database as a user with the ALTER USER system privilege and issue the required commands.

Note the following SQL script for changing the default roles of selected users. It changes the default role setting so that any role subsequently granted to the user cannot be the default role of that user. To change this, register the user and then issue a the following command:

alter user username default role all except OWB$CLIENT

Editing User Profiles

For each user, you can enter an optional description, assign the user to existing "Roles", specify the "Default Object Privilege" and the "System Privileges".

These are Oracle Database users, so you cannot rename a user in Oracle Warehouse Builder; you must do that trough Oracle Database.

Granting or revoking of roles and privileges only takes effect in the next session Oracle Warehouse Builder.

To edit a user profile:

1. In the Globals navigator, expand Security.

2. Expand Users.

3. Select the name of the user for editing. Right-click the user name, and select Open.

4. The Edit User: Username screen appears. It contains the following options for editing

- Name: you cannot change the name itself, but the screen contains an editable Description text field.

- Roles: you may assign various roles to the user by moving them from the list of Available Roles to the list of Granted Roles.

- Default Object Privilege: you may assign default privileges to either Users or Roles by checking the appropriate boxes under FULL_CONTROL, EDIT, COMPILE, or READ.

- System Privilege: you may assign system privileges to the user by checking appropriate boxes under Object System Privilege (ACCESS_PUBLIC_VIEW_BROWSER, CREATE_PLATFORM, CREATE_PROJECT, or CREATE_SNAPSHOT) and Control Center System Privilege (CONTROL_CENTER_DEPLOYMENT, CONTROL CENTER_EXECUTION, or CONTROL_CENTER_VIEW).

5. When the edits are complete, click OK.

Roles

You can assign a user to one or more roles. If you assign multiple roles with conflicting privileges, then the user is granted the more permissive privilege, which is the union of all the privileges granted to the multiple roles. For example, if you assign to the same user a role that allows creating a snapshot and a role that restricts it, then the user is allowed to create snapshots.

To assign a user to a role that does not display on the Available Roles List, close the editor, create the new role, and then edit the user account. To create a role, right-click Roles under the Security node in the Globals Navigator and select New Role. For information on creating and editing roles, see "Defining Security Roles" and "Editing Role Profiles".

Default Object Privilege

Default object privileges define the access other users and roles have to objects that the selected user creates. These privileges do not impact the privileges the user has for accessing objects created by other users.

For example, for all objects that JANE_DOE creates, JANE_DOE, and ADMINISTRATOR and DEVELOPMENT roles, have full access. EVERYONE, PRODUCTION, and TEST roles are restricted to read-only.

Description of the illustration object_priv_01.gif

If you are familiar with UNIX operating system security, the default object privilege is similar to the UMASK command. When you edit the default object privilege, the change only effects objects the user creates subsequently; there is no effect on previously created objects. Therefore, if you set default object privileges early, you can expect little or no additional object-level security management.

To define the privileges other users have to objects the selected user creates, check the appropriate box for each role or user. You can grant the following privileges: "FULL CONTROL", "EDIT", "COMPILE", and "READ". All the privileges are additive. If you select COMPILE, then you apply both the compile and read privileges.

Access may be granted both to roles and to individual users. Note, however, that when you grant access to a role, the privilege is extended to all users in that role. For example, even though JOHN_DOE is not specifically granted access, he has read access through the EVERYONE role. Furthermore, if JOHN_DOE is a member of the DEVELOPMENT role, he has full control and access.

By default, when you create a new user, the EVERYONE role has full control on all objects. To enable metadata security, edit all user profiles and restrict the access the EVERYONE role has to objects each user creates.

Securing Metadata Objects Throughout their Life Cycle

Default object privileges work with object security properties to provide security options throughout the life cycle of a given metadata object. Settings you specify on the Default Object Privilege tab persist until a qualified user overrides the restrictions, on an object-by-object basis.

Assume that JANE_DOE creates several mappings. When JANE_DOE designs and develops these objects, the security policy described earlier in this section may be desirable. However, assume that JANE_DOE completes the mappings and releases the objects to the testing team. In this case, the default object privilege is too restrictive. To extend access to the TEST role, JANE_DOE can select the mapping, then from the View menu, select Security. She can then manually add all necessary privileges to the TEST role.

Description of the illustration object_priv_02.gif

For more details on overriding the default security on an object by object basis, see "Applying Security Properties on Specific Metadata Objects".

Object Privileges

Object privileges apply to all metadata objects in the repository including projects, modules, and collections.

FULL CONTROL

Full control includes all the other privileges plus the ability to grant and revoke privileges on an object. Only users with full control over an object can override default security on an object-by-object basis as described in "Applying Security Properties on Specific Metadata Objects".

EDIT

The edit privilege includes the compile, and read privileges. Additionally, edit allows users to delete, rename, and modify an object.

COMPILE

The compile privilege includes the read privilege and enables you to validate and generate an object.

READ

The read privilege enables you to view an object.

System Privileges

System privileges define user access to workspace-wide services. Use the System Privilege tab to allow or restrict users and roles from performing administrative tasks.

You can control access to the following operations:

Description of the illustration system_priv_01.gif

- ACCESS_PUBLICVIEW_BROWSER: Allows users to access the Repository Browser.

- CREATE_PLATFORM: Allows users to create new platforms in the workspace using OMB*Plus.

- CREATE_PROJECT: Enables users to create projects, which administrators create projects to organize metadata objects.

- CREATE_SNAPSHOT: Enables users to create snapshots which administrators use when backing up workspaces.

- CONTROL_CENTER_DEPLOYMENT: Enables users to deploy to the Control Center and then run those procedures.

- CONTROL_CENTER_EXECUTION: Enables users to run procedures from the Control Center.

- CONTROL_CENTER_VIEW: Enables users to view procedures from the Control Center.

Support for a Multiple-user Environment

Oracle Warehouse Builder enables multiple users to access the same Oracle Warehouse Builder repository at the same time by managing read/write privileges. Only one user is given write privileges to an object at any given time. All other users can have read-only access. If a user has write access to an object, Oracle Warehouse Builder maintains a lock on the object while the object editor is open. If no changes were made to the object, then the lock is released as soon as the object editor is closed. If changes were made, then the lock is maintained until the user closes all editors associated with the object and either saves the changes or reverts to the last saved version. Other users cannot delete an object while it is in use.

Read/Write Mode

Whenever you open an editor, property sheet, or dialog box, you access objects in read/write mode by default. Your changes are available to other users only after you save them to the repository.

Read-Only Mode

If you attempt to open an object locked by another user, or if you have only READ permissions for the object, then Oracle Warehouse Builder displays a message that prompts you either to cancel the request or access the object in read-only mode. If you choose to continue in read-only mode.

A user who is editing an object in READ/WRITE mode may save changes while a user with read-only privileges views the object. To synchronize the object with the repository, click Refresh.

Defining Security Roles

You can use roles to represent groups of users with similar responsibilities and privileges. Unlike users which are also database users, these roles are not database roles. These roles are purely design constructs for implementing security within the product.

Roles enable you to more efficiently manage privileges because it is more efficient to grant or restrict privileges to a single role rather than multiple users.

The "Everyone Role" and the "Administrator Role" are predefined roles. You edit the privileges but cannot delete or rename the predefined roles.

To create a role:

1. In the Globals navigator, expand Security.

2. Under Security, select Roles.

3. Right-click Roles, and select New Role.
Description of the illustration new_role_01.gif

4. On the Create Warehouse Builder Role screen, enter the Role Name.
Description of the illustration new_role_02.gif

5. Click OK.

Everyone Role

Use this role to easily manage privileges for all users. When you register new users, Oracle Warehouse Builder assigns those users to the EVERYONE role by default.

Administrator Role

Administrators in Oracle Warehouse Builder can perform various security tasks, such as:

- "Registering Database Users"

- "Editing User Profiles"

- Changing User Passwords
You cannot change user passwords from within Oracle Warehouse Builder. Change passwords directly in the Oracle Database as described in Oracle Database Security Guide.

- "Defining Security Roles"

- "Editing Role Profiles"

- Deleting Users and Roles
You may delete users by right-clicking in the Globals navigator, and selecting Delete. You may delete all Oracle Warehouse Builder users expect the repository owner. It does not delete or alter the user account in the Oracle Database.

You can delete all Oracle Warehouse Builder users expect for the design repository owner. Deleting a user from Oracle Warehouse Builder does not delete or alter the user account on the Oracle Database.

You can delete all Oracle Warehouse Builder roles expect ADMINISTRATOR and EVERYONE roles. Deleting a role from Oracle Warehouse Builder does not delete or alter roles in the Oracle Database.

- Renaming Roles
From the Globals Navigator, right-click a role and select Rename. You can rename all roles expect the predefined administrator and everyone roles.

- "Applying Security Properties on Specific Metadata Objects"

Editing Role Profiles

For each role that you create, you can edit the name, enter an optional description, assign the role to existing "Users", and specify the system privilege. You cannot rename or edit the descriptions for the predefined roles EVERYONE and ADMINISTRATOR, nor can you delete them. Oracle Warehouse Builder roles and database roles are separate constructs; therefore, deleting an Oracle Warehouse Builder role has no effect on the database. For more information on system privilege, see "System Privileges".

To alter default security privileges for a role:

1. In the Globals navigator, expand Security.

2. Under Security, expand Roles.

3. Select the role to edit, and right-click. From the menu, select Open.
Description of the illustration edit_role_01.gif

4. In the Edit Role: RoleName window, you may do any following:

- Name: you cannot change the name itself, but the screen contains an editable Description text field.
Description of the illustration edit_role_02.gif

- User: you may assign various users to the role by moving them from the list of Available Users to the list of Grantees.
Description of the illustration edit_role_03.gif

- System Privilege: you may assign system privileges to the role by checking appropriate boxes under Object System Privilege (ACCESS_PUBLIC_VIEW_BROWSER, CREATE_PLATFORM, CREATE_PROJECT, or CREATE_SNAPSHOT) and Control Center System Privilege (CONTROL_CENTER_DEPLOYMENT, CONTROL CENTER_EXECUTION, or CONTROL_CENTER_VIEW).
Description of the illustration edit_role_04.gif

5. When the edits are complete, click OK.

Users

You can assign multiple users to a role. To assign a user that does not display on the Available Users list, then close the editor, create the user from the Security node in the Globals Navigator, and then edit the role. To create a user, right-click Users from the Security node and select New User. For information on creating and editing users, see "Registering Database Users" and "Editing User Profiles".

Applying Security Properties on Specific Metadata Objects

You can grant or restrict access to metadata objects on an object-by-object basis.

To change security properties of a specific metadata object:

1. Select the metadata object for changing.

2. From the View menu, select Security.

3. Edit the security privileges for the object, granting and revoking them either at Role level, or at User level.
Description of the illustration object_priv_03.gif

4. When all changes are made, from the File menu, select Save All.
Confirm changes.

Security Tab

Use the Security tab to define metadata security on an object-by-object basis. Only users that have full control privileges on an object can change the metadata access controls on the Security tab. Security properties are important in managing the life cycle of your projects, as described in "Example: Using Security Properties to Freeze a Project Design".

While the "Default Object Privilege" defines metadata security for objects a specific user creates, the Security tab overrides that metadata security policy on an object-by-object basis. Assume that JANE_DOE is a developer that creates mappings and process flows. If you want all objects created by JANE_DOE made available to another developer, such as JOHN_DOE, then use the "Default Object Privilege". However, to make only a few objects created by JANE_DOE available to JOHN_DOE or even every user who has a TEST role, locate each object in the Design Center and alter its security options.

To enforce a full metadata strategy, edit the security properties for all projects in the Project navigator. By default, the EVERYONE role has its object privileges set to full control. Change the EVERYONE role privilege to be more restrictive and select Propagate Security Settings icon to apply the changes to all children.

Propagating Security Properties to Child Objects

You can apply security properties to an object and all its children by selecting Propagate on the Security tab. This option is disabled when you select an object that cannot have child objects.

Example: Using Security Properties to Freeze a Project Design

When users complete the design of a project, you may want to freeze the contents of the project. After you complete the following steps, only administrators can change the objects in the project.

To freeze a project design:

1. Log on as user with administrator privileges.

2. From the View menu, select Security.
Description of the illustration security_03.gif

3. On the Security tab, restrict the privileges for all users and roles other than the administrators, as appropriate.

4. Click Propagate Security Settings icon.

Security Enforcement

When any user attempts to perform an operation in Oracle Warehouse Builder, it first verifies that the user has the required privileges to perform the operation. Table 13-1 lists the privileges required to run operations in Oracle Warehouse Builder.

Table 13-1 Privileges Required for the Execution of Operations

Oracle Warehouse Builder Operation

Security Check

Configure

User must have EDIT privilege on objects to be configured.

Copy

User must have READ privilege on the object to be copied.

Create object

User must have EDIT privilege on parent. For example, to create a mapping you must have EDIT privilege on the module.

Cut

User must have EDIT privilege on the object to be cut.

Delete

User must have EDIT privilege on the object to be deleted.

Deploy

User must have CONTROL_CENTER_DEPLOY system privilege.

Edit

User must have EDIT privilege on the object to be edited.

Export

User must have READ privilege on objects to be exported. Administrative users can export security information such as roles, users, and privileges when Export security information is enabled.

Generate

User must have COMPILE privilege on object to be generated.

Import

User must have EDIT privilege on objects to be exported. Administrative users can import security information such as roles, users, and privileges when Import security information is enabled.

Move

User must have privileges listed for the Cut and Paste operations.

Paste

User must have EDIT privilege on the parent to receive the copied object.

Rename

User must have EDIT privilege on the object to be renamed.

Snapshot: compare snapshots

To compare with another snapshot or other repository object, user must have READ privilege on that snapshot and the snapshot or other repository object.

Snapshot: restore snapshot

To restore an object based on a snapshot, a user must have READ privilege on that object. To restore a folder, a user must have EDIT privilege on the folder and all of its children.

Snapshot: take snapshot

User must have the CREATE_SNAPSHOT system privilege to create snapshots.

Source import

User must have EDIT privilege on objects to be replaced by imported objects.

Synchronize inbound

User must have READ privilege on the object in the repository and EDIT privilege on the object in the editor.

Synchronize outbound

User must have EDIT privilege on the object in the repository.

Validate

User must have COMPILE privilege on object to be validated.

Managing Passwords in Oracle Warehouse Builder

You can manage passwords within Oracle Warehouse Builder in the following ways:

- "Credential Memory on Logon Panel"

- "Changing Passwords that Access Control Centers"

- "Encrypting Passwords to Oracle Warehouse Builder Locations"

Credential Memory on Logon Panel

The logon dialog that appears when Oracle Warehouse Builder Design Center is started retains a list of previously used credentials. This is a convenience for Design Center users who frequently work with the same workspaces. The feature enables Oracle Warehouse Builder to remember log in information.

Changing Passwords that Access Oracle Warehouse Builder

In keeping with standard security practices, you may want to periodically change the passwords used to access Oracle Warehouse Builder repositories.

Changing Passwords that Access Design Repositories

Manage the password to design repositories as you would any other Oracle Database.

Changing Passwords that Access Control Centers

To change the password for a repository that hosts a Control Center and is therefore a deployment environment, you must first stop the Control Center service, run a script to change the password, and restart the Control Center service.

To change the password for a repository that hosts a Control Center:

1. Log on to the Control Center as the repository owner.

2. Stop the Control Center by running the script OWB_HOME/owb/rtp/sql/stop_service.sql.
The script returns values of Unavailable or Available to indicate the status of Control Center.

3. Change the password by running the script OWB_HOME/owb/rtp/sql/set_repository_password.sql.
When prompted, specify the new password.

4. Restart the Control Center by running the script
OWB_HOME/owb/rtp/sql/start_service.sql.

Encrypting Passwords to Oracle Warehouse Builder Locations

Oracle Warehouse Builder users create a location for each database, file server, or application that want to extract or load metadata and data. Locations include the user name and password used to access these various sources and targets. Oracle Warehouse Builder can store these passwords in the repository in an encrypted manner. The switch that turns on and off the password storage is Persist Location Password in Metadata, which is located in the Design Center under Tools, Preferences, Security Parameters.

The default encryption algorithm utilized is DES56C that is valid for Oracle9i and subsequent versions. If the repository Database is version 10g or later, then you can set the encryption algorithm to 3DES168 or any other more powerful encryption by changing OWB_HOME/owb/bin/admin/jdbcdriver.properties file and specifying the following encryption parameters:

encryption_client; default = REQUIRED
encryption_types_client; default = ( DES56C )
crypto_checksum_client; default = REQUESTED
crypto_checksum_types_client; default = ( MD5 )

For the protocol to work, set the server to the default ACCEPTED mode. For more information, see Oracle Database JDBC Developer's Guide.

A Troubleshooting the Installation and Setup

This section describes some troubleshooting tasks you must perform during installation and setup of Oracle Warehouse Builder.

This section includes the following topics:

- "General Steps for Troubleshooting Oracle Warehouse Builder"

- "Inspecting Log Files in Oracle Warehouse Builder"

- "Error Messages Related to Installation"

- "Troubleshooting Other Installation Problems"

- "Checking the Java Virtual Machine (JVM)"

- "Using Oracle Warehouse Builder Client Logging to Control Logging and Trace Problems"

- "Checking the System Path of Oracle Warehouse Builder"

- "Configuring Oracle Warehouse Builder for Oracle RAC"

General Steps for Troubleshooting Oracle Warehouse Builder

Take the following steps to troubleshoot errors in Oracle Warehouse Builder:

1. Review this section for a possible solution to the problem.
If Oracle Warehouse Builder displays an error message during the installation process, then refer to "Error Messages Related to Installation". If you did not note the error number, you can review the "Log Files for Installation Errors".

In the absence of an error message, refer to "Troubleshooting Other Installation Problems".

2. Check for additional information about the problem by "Inspecting Log Files in Oracle Warehouse Builder".

3. If the problem remains unresolved, search for a possible solution at My Oracle Support at https://support.oracle.com/.

4. From the Repository Assistant, use the Check for Updates Wizard to see if there is a patch or information that addresses the problem. See "About the Check for Updates Wizard for Oracle Warehouse Builder".

5. Review the Oracle Warehouse Builder Release Notes for installation notes or known issues.

6. If you are unable to resolve the problem in the previous steps, contact Oracle Support.
Oracle Support may ask you to complete the steps in "Using Oracle Warehouse Builder Client Logging to Control Logging and Trace Problems".

Inspecting Log Files in Oracle Warehouse Builder

This section outlines all the different types of error messages that are logged by Oracle Warehouse Builder and how to access them.

Oracle Warehouse Builder logs the following types of errors:

- "Log Files for Installation Errors"

- "Log Files for Metadata Import and Export Errors"

- "Log File for Validation Errors"

- "Log File for Generation Errors"

- "Log Files for Deployment and Execution Errors"

- "Log File for Name and Address Server Errors"

Log Files for Installation Errors

When you run Oracle Universal Installer to install Oracle Warehouse Builder, the installation error logs are automatically stored in:

C:\ProgramFiles\Oracle\Inventory\logs\installActionstimestamp.log

When you run the Oracle Warehouse Builder Repository Assistant, the workspace installation error logs are stored in:

OWB_HOME\UnifiedRepos\log_timestamp.log

See "Error Messages Related to Installation" for suggested actions for commonly encountered errors during installation.

Log Files for Metadata Import and Export Errors

Metadata Import: When you import a project or specific objects into your workspace using the Metadata Import Utility, Oracle Warehouse Builder records details of the import process in a log file. You can specify the name and location of this log file from the Metadata Import dialog box.

Metadata Export: When you export an Oracle Warehouse Builder project or specific objects using the Metadata Export Utility, Oracle Warehouse Builder records the details of the export in a log file. You can specify the name and location of this log file from the Metadata Export dialog box.

Log File for Validation Errors

In Oracle Warehouse Builder, you can validate all objects by selecting the objects from the console tree and then selecting Validate from the Object menu. After the validation is complete, the validation messages are displayed in the Validation Results window.

You can also validate mappings from the Mapping Editor by selecting Mapping, then Validate. The validation messages and errors are displayed in the Validation Results window.

On the Validation tab of the Validation Results window, double-click an object name in the Object column to display the editor for that object. You can fix errors in the editor. Double-click a message in the Message column to display the detailed error message in a message editor window. To save the message to your local system, select Code in the menu bar, then select Save as File.

Oracle Warehouse Builder saves the last validation messages for each previously validated objects. You can access these messages at any time by selecting the object from the console tree in the Project Navigator, select View from the menu bar, and then click Validation Messages. The messages are displayed in the Validation Results window.

Log File for Generation Errors

After you generate scripts for Oracle Warehouse Builder objects, the Generation Results window displays the generation results and errors. Double-click an error under the Messages column on the Validation tab to display a message editor that enables you to save the errors to your local system.

After you generate scripts for Oracle Warehouse Builder objects, the Generation Results window displays the generation results and errors. Double-click an error under the Messages column on the Validation tab to display a message editor that enables you to save the errors to your local system.

Log Files for Deployment and Execution Errors

You can store execution or deployment error and warning message logs on your local system by specifying a location for them. In the Project Navigator, select the project. Then from the Tools menu, select Preferences. In the Preferences dialog box, click the Logging option in the object tree to the left. In the list box on the right, you can set the log file path, file name and maximum file size. You can also select the types of logs you want to store.

You can view this log of deployment and error messages from the Oracle Warehouse Builder console by selecting View from the menu bar, and then Messages Log. This Message Log dialog box is read-only.

Errors related to the Control Center Service are stored at the following path:

OWB_HOME\log\Repository_Name\log.xx on Oracle Database server.

Errors related to transforming or loading data are stored in the Control Center audit tables. You can access these error reports using the Repository Browser. The Browser provides detailed information about past deployments and executions. Click the Execution tab in the Execution reports to view error messages and audit details.

Log File for Name and Address Server Errors

If you are using the Name and Address cleansing service provided by Oracle Warehouse Builder, you can encounter related errors.

Name and address server start and execution errors can be located at:

OWB_HOME\owb\bin\admin\NASver.log

If your Name and Address server is enabled in:

OWB_HOME\owb\bin\admin\NameAddr.properties:TraceLevel=1,

then it produces the log file NASvrTrace.log.

Error Messages Related to Installation

This section includes the following topics:

- "No fonts were found in 'drive:\Program Files\ Qarbon\viewlet Builder3jre\lib\fonts'"

- "OWBSYS is not granted access to OWB_HOME/owb/bin/admin/rtrepos.properties: Please run UnifiedRepos/reset_owbcc_home.sql, specifiying the path of Oracle home from which the Control Center Service is being run."

- "SYS user does not have SYSDBA privileges."

- "RTC-5301: The Control Center Service is not currently available."

- "API5022: Cannot Connect to the Specified Repository"

- "Run-time Assistant fails with LoadJava Error."

- "Error when specifying a SYSDBA user."

- "Regional Name and Address Data Libraries Are Not Available."

- "Lineage and impact analysis reports: Extensive tablespace requirements for materialized views."

- "Java out of memory error occurs during a batch operation."

- "ORA-01925: Maximum of 30 enabled roles exceeded"

- "INS0009: Unable to connect to the database. Verify the connect information."

- "INS0022: A spawned program error."

- "ORA-12154: TNS: Could not resolve service name."

- "ORA-12514: TNS: listener could not resolve SERVICE_NAME given in connect descriptor."

- "PL/SQL: ORA-04052: Error occurred when looking up remote object"

- "IMP-00003: ORACLE error 30371 encountered ORA-30371: column cannot define a level in multiple dimension"

- "Unable to connect to SQL*Plus in Oracle Database version"

- "ORA-04020 deadlock detected while trying to lock object or ORA-04021 timeout occurred while waiting to lock object"

- "ORA-04088: error during execution of trigger 'DVSYS.DV_BEFORE_DDL_TRG'"

- "DPF-0029: Source Table_Name must have less than 165 attributes"

Causes and Actions

No fonts were found in 'drive:\Program Files\ Qarbon\viewlet Builder3jre\lib\fonts'

Cause: After installing Oracle Warehouse Builder client components, you installed another software program that relies on Jinitiator and overwrote Java objects necessary for Oracle products. This may prevent you from starting Oracle Oracle Warehouse Builder or any other Oracle product that depends on Java objects.

Action: Re-install Jinitiator.

OWBSYS is not granted access to OWB_HOME/owb/bin/admin/rtrepos.properties: Please run UnifiedRepos/reset_owbcc_home.sql, specifiying the path of Oracle home from which the Control Center Service is being run.

Cause: When running the script reset_owbcc_home.sql and prompted for the OWB_HOME, you typed an invalid path for OWB_HOME.

Action: Run the script again and enter the correct path.
On all platforms, including both Windows and UNIX, the path you enter must use forward slashes, and is case-sensitive. The case of the path entered here must match the case of the path for the Oracle Warehouse Builder home as known by the operating system.

On UNIX, the correct path to enter is the path for the OWB_HOME directory. On Windows, to determine the correct path for the OWB_HOME directory, and examine the path displayed as part of the default Windows command prompt.

SYS user does not have SYSDBA privileges.

Cause: In a standard database installation, the SYS user has SYSDBA credentials and REMOTE_LOGIN_PASSWORDFILE=EXCLUSIVE. You can verify the credentials by issuing the following connect statement:
SQL> CONNECT sys@tns_name_of_db AS SYSDBA;

Enter password: sys_password

If your database is configured with REMOTE_LOGIN_PASSWORDFILE=NONE, then the statement fails.

Action: If the statement fails, then you have the following options:

- Reconfigure your database with
REMOTE_LOGIN_PASSWORDFILE=EXCLUSIVE and create a password file if none exists.

- If the preceding is not an option, reconfigure your database with
O7_DICTIONARY_ACCESSIBILITY=TRUE.

RTC-5301: The Control Center Service is not currently available.

Cause: A Control Center Service must be running to enable the Control Center to manage deployments and executions. The service connects to the Control Center using JDBC and can be run from any Oracle Warehouse Builder home. Normally the service is runs on the server host.

Action: You can start a service on the server host by using the script start_service.sql.
If it is not possible to run the service on the server host, then start the Control Center Service on the local computer using the script local_service_login.sh or local_service_login.bat as appropriate. Use this script as follows:

local_service_login.sh [-startup | -closedown] OWB_HOME

In this mode, the Control Center Service runs on the local computer and is available only when that computer is available and can connect to the Control Center.

Use the script show_service.sql to determine the status of the service.

Control center service log file reports "DBMS_OBFUSCATION" or "No key is found."

Cause: The encryption of the passwords is out of sync with the client.

Action: Reset the repository and restart the control center service. To reset the repository, run owb/rtp/sql/reset_repository.sql.

API5022: Cannot Connect to the Specified Repository

This error occurs when you try to connect to the repository after having performed a database export or import from the Oracle Warehouse Builder repository schema.

Cause: The package NAMESPACESERVICEIMPL may be invalid. This occurs after a database export or import from the Oracle Warehouse Builder repository schema if the repository owner has no SELECT privilege on SYS.V_$SESSION. You can diagnose the cause as follows:

1. In SQL*Plus, connect to the Oracle Warehouse Builder repository schema.

2. Enter the following command at the SQL prompt:

ALTER PACKAGE NAMESPACESERVICEIMPL compile body;

3. If Warning: Package body altered with compilation errors appears, enter the following command at the SQL prompt:

show errors;

4. The following errors mean that the Oracle Warehouse Builder repository owner has no SELECT privilege on SYS.V_$SESSION.

PL/SQL: SQL statement ignored
PLS-00201: Identifier 'SYS.V_$SESSION' must be declared

Action: Complete the following steps:

1. In SQL*Plus, connect as the SYS user.

2. At the SQL prompt, enter the following command:

grant SELECT on V_$SESSION to Oracle Warehouse Builder_Repository_Owner;

3. Connect to the Repository_Owner.

4. Enter the following command at the SQL prompt:

alter package NAMESPACESERVICEIMPL compile;

Run-time Assistant fails with LoadJava Error.

Cause: This can occur if the Oracle Database does not have the JServer option installed.

Action: Make sure that the Oracle Database has JServer option installed.

Error when specifying a SYSDBA user.

Oracle Warehouse Builder Assistants require you to provide SYSDBA credentials when installing the Oracle Warehouse Builder Design Repository or run-time components.

Cause: In a standard database installation, the SYS user has SYSDBA credentials. You can verify this from SQL*Plus by issuing the following connect statement:
connect sys/sys_password@TNS_NAME_OF_DB as sysdba;

In a standard database installation, the preceding connect statement works because REMOTE_LOGIN_PASSWORDFILE=EXCLUSIVE and the default password file is created by the installation process.

If your database is configured with

REMOTE_LOGIN_PASSWORDFILE=NONE, then the following statement fails:

connect sys/sys_password@TNS_NAME_OF_DB as sysdba;

In this case, you have two options.

Action: Reconfigure your database with
REMOTE_LOGIN_PASSWORDFILE=EXCLUSIVE and create a password file if none exists.

Action: If the preceding is not an option, then reconfigure your database with
O7_DICTIONARY_ACCESSIBILITY=TRUE. With this setting, the statement

connect sys/sys_password@TNS_NAME_OF_DB enables the Oracle Warehouse Builder Assistants to connect to SYS user.

Regional Name and Address Data Libraries Are Not Available.

Cause: The Name and Address regional data libraries may not have been installed in the correct location.

Action: Ensure that you have successfully extracted regional data to the NAS_DATA directory.

1. From the OWB_HOME, start the Name and Address Server:
On Windows, run owb\bin\win32\NAStart.bat.

On Linux, Run owb/bin/unix/NASTART.sh.

2. Open the log file: owb\bin\admin\NASvr.log.
The log contains a list of installed countries.

If there is no such list, then verify that you have extracted the regional library data to the correct location. If you have extracted the data to the wrong location, then you can either reinstall the data, or modify the owb\bin\admin\NameAddr.properties file to indicate the correct file path. If you modify the NameAddr.properties file, then stop and restart the Name and Address Server as follows:

On Windows, start the server by running owb\bin\win32\NAStart.bat. Stop the server by running owb\bin\win32\NAStop.bat.

On UNIX, start the server by running owb/bin/unix/NAStart.sh. Stop the server by running owb/bin/unix/NAStop.sh.

3. After you have verified the installation, you can stop the Name and Address Server if you want, because it is automatically started at the execution of any mapping that employs the Name and Address operator.

Lineage and impact analysis reports: Extensive tablespace requirements for materialized views.

The first time you refresh a materialized view, it is populated from the Oracle Warehouse Builder repository. The materialized view can occupy up to twice the amount of space allocated to the entire Oracle Warehouse Builder repository.

Cause: Insufficient space has been allocated to the Oracle Warehouse Builder repository schema.

Action: If Oracle Warehouse Builder repository schema is created in a tablespace that is dedicated to its use, these issues are easier to monitor. Ensure that sufficient free space exists on the physical drive for tablespace expansion. Within Oracle Enterprise Manager, ensure that the tablespace is set to Autoextend On.

Note:
To grant permission to an Oracle Warehouse Builder repository user to use Enterprise Manager for performing tasks, enter the following command in SQL*Plus: GRANT SELECT any dictionary to "&OWB repository user";

Java out of memory error occurs during a batch operation.

Operations requiring large amounts of memory can result in a Java out of memory error, if the system resources (such as virtual memory) are constrained.

Cause: There is not enough virtual memory. Oracle Warehouse Builder client runs with a maximum heap size, as defined by the -mx parameter in the owbclient.bat file. The -Dlimit parameter in the owbclient.bat file specifies the memory threshold (80% of Dlimit) at which Oracle Warehouse Builder memory manager begins to assist Java garbage collection. If you change the -mx parameter value, set the -Dlimit parameter to the same value, or at least to 90% of the value. Setting the -Dlimit to a low value can have a negative impact on the performance of Oracle Warehouse Builder.

Action: Increase the -Dlimit parameter in Oracle Warehouse Builder as follows:

1. Exit Oracle Warehouse Builder.

2. Open this file in a text editor:
On Windows, open the $OWB_HOME\bin\win32\ombplus.bat.

On UNIX, open the $OWB_HOME\bin\win32\owbclient.sh.

3. Change the -Dlimit parameter to 334.

4. Save and close the file.

5. Restart Oracle Warehouse Builder.

ORA-01925: Maximum of 30 enabled roles exceeded

This error occurs when installing a repository or a target schema.

Cause: The maximum number of enabled roles in the database has been exceeded. When you create a repository or a target schema, new roles are created in the database assigned to the schema in question. When the number of roles exceeds the value of the MAX_ENABLED_ROLES parameter, this error occurs.

Action: Increase the value of the MAX_ENABLED_ROLES parameter in the init.ora file. When you uninstall a repository or a target schema, delete the associated roles as well.

INS0009: Unable to connect to the database. Verify the connect information.

This error occurs when you try to connect to a database.

Cause: See the cause for "ORA-12514: TNS: listener could not resolve SERVICE_NAME given in connect descriptor."

Action: Follow the instructions for "ORA-12514: TNS: listener could not resolve SERVICE_NAME given in connect descriptor."

INS0022: A spawned program error.

Cause: This error message can result from a server issue when installing Oracle Warehouse Builder run-time components on an HP-UX operating system.

Action: To identify the server issue, complete the following steps:

1. From SQL*Plus, connect to a SYS user.

Create user test_lj identified by test_lj;
Grant connect, resource to test_lj;

2. Create OWB_HOME/owb/bin/unix/test.sh with the following contents:

../unix/loadjava -thin -verbose -order -resolve -user
'test_lj/test_lj@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=hpdgpa3)(PORT=1522))(CONNECT_DATA=(SERVICE_NAME=dgpadw)))'
../../lib/int/rtpserver.jar

3. Change directory to OWB_HOME/owb/bin/unix/.

4. Run test.sh.

ORA-12154: TNS: Could not resolve service name.

This error occurs when you try to connect to a database.

Cause: You defined an Oracle Warehouse Builder location and specified connection information using SQL*Net. However, the required TNS name is not accessible.

Action: To set up a TNS name for use during deployment in general and for execution of mappings and process flows, the TNS name must be accessible from the OWB_HOME being used to run the control center service. To ensure access, run the Net Configuration Assistant from the OWB_HOME and then restart the control center service.
To set up a TNS name for use by database links, the TNS name must be accessible from the database server home. To ensure access, run the Net Configuration Assistant from the database server home.

Cause: See the cause for "ORA-12514: TNS: listener could not resolve SERVICE_NAME given in connect descriptor."

Action: Follow the instructions for "ORA-12514: TNS: listener could not resolve SERVICE_NAME given in connect descriptor."

ORA-12514: TNS: listener could not resolve SERVICE_NAME given in connect descriptor.

This error occurs when you try to connect to a database.

Cause: If you used Oracle Net Easy Configuration or Oracle Net Assistant to create the Net Service Name entry, and you used the default option (Service Name) on the newly created Net Service Name, then the parameter SERVICE_NAME is added to the TNSNAMES.ORA as a subclause to the CONNECT_DATA section in the Net Service Name entry. This replaces the (SID=SIDname) subclause in previous releases of the database, for example, Oracle Database8i (8.1.x).

Action: Implement the TNSNAMES.ORA file as follows:

1. Use the GLOBAL_DBNAME parameter in the LISTENER.ORA for each SID to identify as a separate service. Use the value of this parameter as the value of the SERVICE_NAME parameter. You must activate any changes that you make to LISTENER.ORA for this purpose by stopping and restarting the listener process.

2. Use the values of the parameters that exist in the INIT.ORA, namely SERVICE_NAMES and DB_DOMAIN, to determine the value of the SERVICE_NAME that you must use in TNSNAMES.ORA. The valid construction of this value is SERVICE_NAMES.DB_DOMAIN with the period separating the two INIT.ORA values. If your SERVICE_NAMES is BIKES and your DB_DOMAIN is COM, then your SERVICE_NAME is BIKES.COM.

3. If there is no DB_DOMAIN parameter set in your INIT.ORA, or if there is no GLOBAL_DBNAME in the LISTENER.ORA, then you can use the SERVICE_NAMES from the INIT.ORA in your TNSNAMES.ORA for the SERVICE_NAME parameter.
For example, if INIT.ORA contains SERVICE_NAMES = "TEST817" and db_domain is not set, then the TNSNAMES.ORA entry is: CONNECT_DATA =(SERVICE_NAME = "TEST817")).

4. If you have multiple values specified in the SERVICE_NAMES parameter in the init.ora, then you can use one of them. If SERVICE_NAMES is not set, then you can use DB_NAME.DB_DOMAIN parameters from the INIT.ORA file.

5. If SERVICE_NAMES and DB_DOMAIN is not set in the INIT.ORA and there is no GLOBAL_DBNAME in the LISTENER.ORA, then your SERVICE_NAME in TNSNAMES.ORA file is DB_NAME.

PL/SQL: ORA-04052: Error occurred when looking up remote object

This error occurs when you have upgraded to Oracle Database version and are trying to redeploy mappings without first redeploying connectors.

Cause: While upgrading Oracle Database, you moved your database to a new computer. Your old and new database instances do not have the same domain name. You can verify the cause by logging in to SQL*Plus as a SYS user and entering the following command: SELECT * FROM GLOBAL_NAME; If the Global Name of the old database does not match that of the new database, then a domain mismatch is causing this error.

Action: Either add the domain name to the Global Name in your new database by issuing a command similar to the following statement: ALTER DATABASE RENAME GLOBAL_NAME TO xxx10G.US.ORACLE.COM; or redeploy your connectors.
Refer to Oracle Warehouse Builder User's Guide for information on deploying connectors.

IMP-00003: ORACLE error 30371 encountered ORA-30371: column cannot define a level in multiple dimension

This error occurred when you were importing your target schema during migration.

Cause: Oracle Warehouse Builder target schema is created with the select_catalog_role privilege. If you have the same dimension object defined in multiple Oracle Warehouse Builder target schemas, then Oracle Export creates duplicates in the export file, and this error occurs when you import.

Action: Connect as a SYS user to the existing version of the Oracle Database from which you exported the target schemas. Enter the following statement in
SQL*Plus: revoke select_catalog_role from OLD_Target_Schema;

Export the target schema into an Oracle .DMP file again, and then import the file into Oracle Database.

Unable to connect to SQL*Plus in Oracle Database version

Cause: Your Oracle home or Path is not set correctly, or your Net Service Names are not configured.

Action: Ensure your Oracle home and Path are set correctly, and your Net Service Names are configured in Oracle Database.

- Ensure that OWB_HOME and PATH are set correctly. Your Oracle home directory must to point to the OWB_HOME. Set your PATH variable to include the OWB_HOME\bin directory before any other Oracle products.

- Ensure that the TNSNames.ora file is configured correctly:
On Windows, from Oracle Database program group, start Net Configuration Assistant and select Local Net Service Name Configuration to configure TNSNames.ora.

On UNIX, set OWB_HOME and PATH to the OWB_HOME for Oracle Warehouse Builder 11g Release 2 (11.2) then run OWB_HOME/bin/netca to start Net Configuration Assistant. Select Local Net Service Name Configuration to configure TNSNames.ora.

ORA-04020 deadlock detected while trying to lock object or ORA-04021 timeout occurred while waiting to lock object

When creating run-time objects, the Run-Time Assistant halts and produces these errors in the error log when trying to lock sys.dbms_aq.

Cause: User sessions may be pinning Advanced Queue objects.

Action: First, log in to SQL*Plus as a SYS user and run a query to identify which user sessions are pinning the Advanced Queue packages, using the following query as an example:

column s.sid format a5;
column s.serial# format a8;
column s.username format a10;
column objectname format a10;
select distinct
s.sid,
s.serial#,
s.username,
x.kglnaobj as objectname
from
dba_kgllock l,
v$session s,
x$kgllk x
where
l.kgllktype = 'Pin' and
s.saddr = l.kgllkuse and
s.saddr = x.kgllkuse and
x.kglnaobj in ('DBMS_AQ', 'DBMS_AQADM');

The following is an example of the output you may receive:

SID    SERIAL# USERNAME  OBJECTNAME
---    ------- --------  ----------
9      29623  RTU_4942   DBMS_AQ

Noting the SID and Serial Number, issue the following command to stop the user sessions:

ALTER SYSTEM KILL SESSION 'SIDNoted, SerialNumberNoted';

For example, enter the following command to stop the session listed in the sample output for this error:

ALTER SYSTEM KILL SESSION '9,29623';

ORA-04088: error during execution of trigger 'DVSYS.DV_BEFORE_DDL_TRG'

Cause: When you attempt to create an Oracle Warehouse Builder repository on an Oracle Database that includes the Database Vault option, you may encounter an error such as ORA-04088.

Action: Disable the triggers DV_BEFORE_DDL_TRG and DV_AFTER_DDL_TRG.

Import wizard throws error ORA-00997 when importing a table.

Cause: When you import table definitions from an Oracle Database, you may encounter an error such as "Repository Error Message: ORA-00997: illegal use of LONG data type...". This occurs when the CURSOR_SHARING parameter is set to FORCE or SIMILAR.

Action: Set the database parameter CURSOR_SHARING to EXACT.

DPF-0029: Source Table_Name must have less than 165 attributes

Cause: Creating data profiling on a table having more than 165 columns.

Action: Select a subset of columns from the table for profiling, by defining an attribute set. This is a data profiling restriction.

Troubleshooting Other Installation Problems

This section includes causes and actions for the following installation problems:

- "Warehouse Builder Clients that Previously Started Now Momentarily Display the Splash Screen and Fail to Start"

- "Newly Installed Warehouse Builder Clients Fail to Start and Previously Started Oracle Products Fail to Start"

- "A Warehouse Builder Client Freezes or Hangs"

- "Defining a User and an Owner in the Basic Installation in release 10.2"

Causes and Actions

Warehouse Builder Clients that Previously Started Now Momentarily Display the Splash Screen and Fail to Start

Cause: If you attempt to start an Oracle Warehouse Builder client such as the Design Center and the splash screen displays momentarily but the client fails to start, you may have overwritten required java objects during the subsequent installation of another software product.
If the client is installed on Windows and you started the client from the Start menu, you may not see any error messages.

Action: Manually start the client by typing at the DOS prompt run OWB_HOME\owb\owbclient.bat. You are likely to encounter an error message such as "No fonts were found in 'drive:\Program Files\ Qarbon\viewlet Builder3jre\lib\fonts'".

Newly Installed Warehouse Builder Clients Fail to Start and Previously Started Oracle Products Fail to Start

Cause: After installing Oracle Warehouse Builder software, an error in the path variable can prevent you from starting Oracle Warehouse Builder clients and other Oracle products that previously started without problems.

Action: Verify the that the path for OWB_HOME\bin is listed correctly in the Environmental Variables.

A Warehouse Builder Client Freezes or Hangs

Cause: Client software may freeze or hang due to various causes.

Action: If an Oracle Warehouse Builder client appears to freeze or hang, perform a stack trace as follows:

1. At the DOS command prompt, enter:
cd OWB_HOME\owb\bin\win32\

2. Run owbclient.bat.

3. When the program hangs, press Ctrl+Break keys.
This produces the thread-dump. Contact Oracle Support and provide them with this information to help identify the problem.

Defining a User and an Owner in the Basic Installation in release 10.2

Cause: If you are upgrading from release 10.2 to 11.2, then you may expect a default repository owner to be assigned as OWBRT_SYS. This is incorrect. This owner is not created.

Action: No action needed.

Checking the Java Virtual Machine (JVM)

To check, verify, or reinstall the Java Virtual Machine (JVM) server in the database, refer to My Oracle Support:

1. In your Web browser, go to the following URL: https://support.oracle.com.

2. Log in to My Oracle Support, or register as a new user.

3. Enter the following terms into the Search field, separating each term by semicolons):
INITJVM.SQL; INSTALL; JAVAVM; JVM; VERIFY; SERVER; INSTALL; CLEANUP

4. Press Enter.

This search returns the support notes for the JVM. The number of available documents frequently changes because My Oracle Support creates, merges, and deletes various support notes. This string of search words returns the most current and pertinent documents.

Using Oracle Warehouse Builder Client Logging to Control Logging and Trace Problems

If Oracle Warehouse Builder is producing errors or exhibiting other unexpected results, additional error logging can help you and Oracle Support identify the cause. You can create a temporary file for logging by using owbclient.logging.properties in Oracle Warehouse Builder user home directory to get trace information from the client. This should only be used for specific troubleshooting as this generates excessive debugging information if left on the system. The following example writes a logging file owbclient.log to /tmp. Using Java logging properties, enter:

console.messageFormat={1,time}: {2}
file.messageFormat=[{3} ({4})] {1,time}: <{0}> {2}
handlers=java.util.logging.FileHandler
java.util.logging.FileHandler.pattern=/tmp/owbclient.log
level = DEBUG_ALL
java.util.logging.FileHandler.level=ALL
java.util.logging.ConsoleHandler.level=DEBUG_ALL

Stop and restart the client for this to take effect. Remember to remove this after you have your log, and then stop and restart the client again.

Checking the System Path of Oracle Warehouse Builder

You must ensure that Oracle Universal Installer added the bin directory of the new Oracle Warehouse Builder 11.2 installation to the system path ahead of other Oracle product bin directories. This is easily checked using the command prompt.

To verify the system path for Oracle Warehouse Builder on Windows:

1. In the Command Prompt window, enter path.

C:\> path

2. The system returns the value of the path variable; verify that C:\OWB112 precedes other Oracle products.

PATH=C:\OWB112\bin;C:\oracle\product\11.2.0\db_1\bin; ... \

To verify the system path for Oracle Warehouse Builder on Linux:

1. Echo the PATH variable in your shell.

Configuring Oracle Warehouse Builder for Oracle RAC

When installing Oracle Warehouse Builder on an Oracle RAC cluster, the Oracle RAC service names must be unique and match the node that they're running on. This ensures that the Control Center Service uses a database service on the correct node, which in turn ensures access to the correct file system.

For example, the wb_rt_service_nodes should be similar to those in Table A-1.

Table A-1 Naming Oracle RAC Service Nodes

Node

Instance

Host

Port

Service Name

1

1

host_1

port_number_1

RACSRVC_1

2

2

host_2

port_number_2

RACSRVC_2

3

3

host_3

port_number_3

RACSRVC_3

Index

A  C  D  E  F  G  H  I  J  K  L  M  N  O  P  R  S  T  U  V  W

A

access

multiple-user access, about, 13.5

read-only mode, 13.5.2

read/write mode, 13.5.1

accessing

Metadata Loader, 12.9.1

adding

workspace user, 3.3, 4.3

adding role, 7.2.4 Administrator role, 13.6.2 application name, 7.2.7 architecture, 1.2 assigning

roles, 13.4.1

roles to users, 13.7.1

security roles, 13.6

system privileges, 13.4.3

audit connection pool, 7.2.9.1 audit data source

configuring, 7.2.3

audit table data source

configuring, 7.2.9.2

audit table logging, 7.2.9

C

cat_owb.sql, 3.2.1, 4.2.1

changing

Control Center Agent settings with JRTAdministratorMBean, 7.2.11.5

metadata, 11.2

passwords, 13.10.2

session timeout, 7.1.1

Check for Updates Wizard, 1.3 clean_owbsys.sql, 3.2.1, 4.2.1, 5.5 cleaning repository

clean_owbsys.sql, 3.2.2, 4.2.2

Linux, 4.2.2

Windows, 3.2.2

Cluster Topology, 7.2.4 Code Template, 7.2.1 code templates

installing, 7.2.12

components, 1.2 configuration architecture, 1 configuring

audit data source, 7.2.3

audit table data source, 7.2.9.2

Control Center Agent security roles, 7.2.4

Control Center Agent server-side logging, 7.2.2

Control Center Agent web service (jrt-web.war), 7.2.8

Control Center service

Linux, 4.2.4

reset_owbcc_home.sql, 3.2.4, 4.2.4

Windows, 3.2.4

on Linux, 4 on Windows, 3 OWB installed as a standalone

Linux, 4.2

Windows, 3.2.1

OWB installed with Oracle Database 11g Release 2

Linux, 4.1

Windows, 3.1

owblient.bat file for memory, A.3 OWBSYS audit connection pool, 7.2.9.1 repository browser environment, 7.1 connecting

database, errors connecting to, A.3

Design Repository, error, A.3

connection

testing, 7.2.9.1

connection pool type, 7.2.9.1 connection pools, 7.2.9.1 context root, 7.2.7 Control Center

enabled roles, A.3

Control Center Agent, 1.2

configuring server-side logging, 7.2.2

deploying to OC4J, 7.2.7

Control Center Agent audit table logging

enabling, 7.2.9

Control Center Agent files, 7.2.11 Control Center Agent runtime log file, 7.2.11.2 Control Center Agent security roles, 7.2.4

configuring, 7.2.4

Control Center Agent settings, 7.2.11.4 Control Center Agent settings with JRTAdministratorMBean

changing, 7.2.11.5

Control Center Agent topology, 1.2.5 Control Center Agent web service

configuring, 7.2.8

Control Center Service, 1.2 Control Center service

configuring

Linux, 4.2.4

Windows, 3.2.4

reset_owbcc_home.sql, 3.2.4, 4.2.4 stopping

Linux, 4.2.2

Windows, 3.2.2

creating

database user, 3.3, 4.3

database users, 13.3.2

JMS queue, 7.2.5

repository workspace

Linux, 3.3

Windows, 4.3

workspace, 3.3, 4.3 creating OWBSYS schema

cat_owb.sql, 3.2.3, 4.2.3

Linux, 4.2.3

Windows, 3.2.3

ct_permissions.properties, 7.2.1

D

data libraries

Name and Address, A.3

data source type, 7.2.9.2 Data Sources, 7.2.9.2 database roles, changing, 13.3.3 database user

creating, 3.3, 4.3

database users

creating in Warehouse Builder, 13.3.2

registering as Warehouse Builder users, 13.3

data-sources.xml, 7.2.3 default object privileges, 13.4.2 defining

security roles, 13.4.3

deleting

repository, 5.5

Repository users, 5.2

schema objects, 5.4, 5.4

workspace, 5.3

workspace owner, 5.3

workspace user, 5.2

deploying

Control Center Agent to OC4J, 7.2.7

deployment errors, A.2

deployment plan, 7.2.7 Design Control Center

enabled roles, A.3

Design Repository

connecting error, A.3

destination name, 7.2.5, 7.2.5 destination type, 7.2.5, 7.2.5 -Dlimit parameter

owbclient.bat file, memory threshold, A.3

dropping

workspace, 5.3

E

E-Business Suite, 7.3

editing user profiles, 13.4

enabling

access to EBS, 7.3

access to metadata, 7.3

Control Center Agent audit table logging, 7.2.9

encrypting passwords, 13.10.3 enforcing security, 13.9 Enterprise Manager, 5.4 error logs

interpreting error logs, A.2

ETL mappings, 1.2.5 execution

errors, A.2

exporting

metadata, for user grants, 12.4.2.2

metadata, for user-defined definitions, 12.4.2.2

metadata, in additional languages, 12.4.2.1

metadata, results, 12.8

metadata, using the Design Center, 12.1

snapshots, 11.2.3.5

F

FND_APPLICATION table, 7.3

FND_APPLICATION_VL table, 7.3

FND_COLUMNS table, 7.3

FND_FOREIGN_KEY_COLUMNS table, 7.3

FND_FOREIGN_KEYS table, 7.3

FND_PRIMARY_KEY_COLUMNS table, 7.3

FND_PRIMARY_KEYS table, 7.3

FND_SEQUENCES table, 7.3

FND_TABLES table, 7.3

FND_VIEWS table, 7.3

G

generation

errors, A.2

GLOBAL_DBNAME parameter

Net Service Name, A.3

H

host name, 5.2

port number, 3.3, 4.3

I

iIntegrating

E-Business Suite, 7.3

import language options, 12.2.3 importing

metadata, combining import modes and matching criteria, 12.2.2

metadata, for security grants, 12.4.4.2

metadata, for user-defined definitions, 12.4.4.2

metadata, in additional languages, 12.4.4.1

metadata, language options, 12.2.3

metadata, results, 12.8

metadata, using the Design Center, 12.2

metadata, validation rules, 12.2.4

snapshots, 11.2.3.5

init.ora file

MAX_ENABLED_ROLES parameter, A.3

install option, 7.5 installating Warehouse Builder

on RAC environment, 2.4

installation

errors, A.2

troubleshooting, A.1

installation architecture, 1 installation configuration

choosing, 1.1

Control Center Agent topology, 1.2.5

multiple database topology, 1.2.3

separate client and database server topology, 1.2.2

separate Client, Control Center Service, and Database Server topology, 1.2.4

single computer topology, 1.2.1

installing

code templates, 7.2.12

earlier database releases, 2.2

JDBC drivers for OC4J, 7.2.10

JServer option, Oracle Database, A.3

on Oracle Database 11g Release 2, 2.1

on server, 2

optional components, 7

Oracle Universal Installer, 2.3

Oracle Workflow, 7.5

Repository Browser, 7.1

standalone software, 2.2

third-party name and address data, 7.4, 7.4

Warehouse Builder, 2.4.1

installing Warehouse Builder

on RAC environment, 2.4

Instance Level Security, 7.2.4 instance level security, 7.2.4 integrating

third-party name and address data libraries, 7.4

J

j2ee-logging.xml, 7.2.2

Java Virtual Machine (JVM)

verifying and reinstalling JVM, A.5

jazn.com, 7.2.4, 7.2.4, 7.2.4 JDBC drivers for OC4J

installing, 7.2.10

JDBC Resources, 7.2.9.2 JDBC resources, 7.2.9.1 JDBC URL, 7.2.9.1 JMS destinations, 7.2.5 JMS queue

creating, 7.2.5

JNDI location, 7.2.5, 7.2.5, 7.2.9.2 JobID file, 7.2.11.3 JRT

owb_abortQueue, 7.2.5

owbQueue, 7.2.5

JRTAdministrator, 7.2.11.5 JRTAdministratorMBean, 7.2.11.5 jrt-internal-log-handler, 7.2.2 JRTWebService, 7.2.8, 7.2.8 jrt-web.war, 7.2.8 jrtws.war, 7.2.8 JServer option

Repository Assistant, for the, A.3

jython_lib.zip, 7.2.1 jython_owblib.jar, 7.2.1

K

km_security_needed, 7.2.1

L

language

select, 3.3, 4.3

LD_LIBRARY_PATH, 7.5 LDAP parameters, 7.5 Level Security, 7.2.4 licence agreement, 2.2 listener.ora file

GLOBAL_DBNAME parameter, A.3

LoadJava error

Repository Assistant, A.3

log files

Metadata Loader logs, 12.7

logging

audit table, 7.2.9

logs

interpreting error logs, A.2

M

mailer parameters, 7.5

managing

workspace, 3.3, 4.3

workspace user, 5.2

materialized views, insufficient table space, A.3 MAX_ENABLED_ROLES parameter, A.3 MaxPermSize, 7.2.1 MDL

see Metadata Loader

memory

errors during batch operation, A.3

metadata, 7.1

changing, 11.2

full security strategy, 13.2.3

import and export errors, A.2

minimal security strategy, 13.2.1

multiuser security strategy, 13.2.2

security, 13.1

upgrading, 12.3

Metadata Export Utility, 12.5.1 metadata import

required access privileges, 12.2

Metadata Import Utility, 12.5.2 Metadata Loader

about, 12.9

accessing, 12.9.1

log files, 12.7

multiple user access, 12.6

results, 12.8

utilities, 12.5

metadata objects

applying security properties, 13.8

metadata repository, 3.2.1, 4.2.1 metadata snapshots, 11.2 modes

read-only mode, 13.5.2

read/write mode, 13.5.1

modifying

OC4J startup script, 7.2.1

multiple database topology, 1.2.3 multiple user access with MDL, 12.6 multiple user ecurity strategy, 13.2.2 multiple-user access

about, 13.5

read-only mode, 13.5.2

read/write mode, 13.5.1

-mx parameter

owbclient.bat file, virtual memory, A.3

My Oracle Support, 2.3

N

Name and Address

regional libraries unavailable, A.3

Name and Address server

errors, A.2

names and addresses

installing third-party data, 7.4

Net Service Name

SERVICE_NAME parameter, A.3

O

object privileges, default, 13.4.2

objects

restoring from snapshots, 11.2.3.4

OC4J startup script

modifying, 7.2.1

oc4j_app_administrators, 7.2.4 oc4jadmin, 7.2.4 oc4j-administrators, 7.2.4 ODL job log files, 7.2.11.1 opmn.xml, 7.2.1 optional components

installing, 7

Oracle Database

JServer option, A.3

Oracle service name, 3.3, 4.3, 5.2 Oracle Workflow

installing, 7.5

ORACLE_HOME, 7.5 ORACLE_PORT, 7.5 ORACLE_SID, 7.5 OWB Browser, 1.2 OWB software

uninstalling, 5.6

OWB_INTERNAL_USERS, 7.2.4 OWB_J2EE_ADMINISTRATOR, 7.2.4, 7.2.4 OWB_J2EE_EXECUTOR, 7.2.4, 7.2.4 OWB_J2EE_OPERATOR, 7.2.4, 7.2.4 OWB_USER, 7.5 owbclient.bat file

-Dlimit memory threshold parameter, A.3

-mx virtual memory parameter, A.3

OWBSYS

creating, 3.2.3

definition, 2.1

unlocking, Linux, 4.1

unlocking, Windows, 3.1

OWBSYS account, 2.1 OWBSYS audit connection pool

enabling, 7.2.9.1

OWBSYS schema

creating

Linux, 4.2.3

Windows, 3.2.3

OWBSYS_AUDIT

definition, 2.1

unlocking, Linux, 4.1

unlocking, Windows, 3.1

owbsys_audit, 7.2.9.1 OWBSYS_AUDIT account, 2.1

P

passwords

changing, 13.10.2

encrypting, 13.10.3

in Warehouse Builder, 13.10

PATH environment variable, 7.2.6 performance

-Dlimit parameter, A.3

performing a stack trace, A.4 PermGen, 7.2.1 persistence, 7.2.5, 7.2.5 port number, 5.2 pre-installation checklist, 2.4.1.1 privileges

default, 13.4.2

object, 13.4.2

SYS user, checking privileges, A.3

system, 13.4.3

Process Flow Editor, 7.5 profiles, role, 13.7 properties

security, 13.8

Python.path, 7.2.1

R

RAC environments, installing Warehouse Builder on, 2.4

read-only mode, 13.5.2

read/write mode, 13.5.1

Realms, 7.2.4, 7.2.4

remote installation

OWB home, 3.3, 4.3

setting OWB home, 3.2.7, 4.2.7

remote_owb_install.sql, 3.2.1, 4.2.1 Repository, 1.2 repository

cleaning

Linux, 4.2.2

Windows, 3.2.2

deleting, 5.5 Repository Assistant, 3.2.3, 3.3, 4.2.3, 4.3

LoadJava error, A.3

Repository Assistant, Check for Updates Wizard in, 1.3 Repository Browser

installing, 7.1

repository browser environment

configuring, 7.1

repository objects, 3.2.3, 4.2.3 Repository users, deleting, 5.2 required access privileges

metadata import, 12.2

requirements

JServer option, Oracle Database, A.3

reset_owbcc_home.sql, 3.2.1, 4.2.1 role

adding, 7.2.4

Roles, 7.2.4 roles

Administrator, 13.6.2

assigning, 13.4.1

assigning to users, 13.7.1

available, 7.2.4

changing default, 13.3.3

Everyone, 13.6.1

profiles, 13.7

security, 13.4.3, 13.6

selected, 7.2.4

S

schema objects

deleting, 5.4

schema objects, deleting, 5.4 secure website, 7.2.8 secure-web-site.xml, 7.2.8, 7.2.8 security

enforcement, 13.9

metadata, 13.1

multiple-user access, 13.5

read-only mode, 13.5.2

read/write mode, 13.5.1

roles, 13.4.3

security properties, 13.8 Security Providers, 7.2.4 security roles, 13.6

Control Center Agent, 7.2.4

security strategy

full, 13.2.3

minimal, 13.2.1

multiuser, 13.2.2

select

languages, 3.3, 4.3

separate client and database server topology, 1.2.2 separate Client, Control Center Service, and Database Server topology, 1.2.4 service names

errors resolving service name, A.3

session timeout

changing, 7.1.1

session-config, 7.1.1 setting

PATH environment variable, 7.2.6

setting OWB home

remote installation

Linux, 4.2.7

Windows, 3.2.7

remote_owb_install.sql, 3.2.7, 4.2.7 silent install response values, 2.5 single computer topology, 1.2.1 snapshots

access privileges, 11.2.3.1

adding components, 11.2.2

comparing, 11.2.3.2

converting type, 11.2.3.3

deleting, 11.2.3.6

exporting, importing, 11.2.3.5

metadata, 11.2

restoring, 11.2.3.4

uses, 11.2

standalone software

download, 2.2

SYS password, 7.5 SYS user

verifying privileges, A.3

SYSDBA privileges

checking for SYS user, A.3

system privileges, 13.4.3

T

tablespace, 7.5

select, 3.3, 4.3

tablespace, and materialized views, A.3 tablespaces

materialized views, allocation for, A.3

setting for Control Center, A.3

Target Schema

enabled roles, A.3

testing

connection, 7.2.9.1

web service, 7.2.8

third-party name and address data

installing, 7.4

third-party name and address data libraries

integrating with, 7.4

TNS connect descriptor, 7.5 tnsnames.ora file

SERVICE_NAME parameter, A.3

troubleshooting

installations, A.1

U

uninstalling

OWB software, 5.6

uninstalling OWB, 5 unlocking OWBSYS, 3.2.5, 4.2.5 unlocking OWBSYS_AUDIT, 3.2.5, 4.2.5 unregistering

workspace user, 5.2

user profiles, editing, 13.4 users

assigning roles to, 13.7.1

creating in Warehouse Builder, 13.3.2

registering as Warehouse Builder users, 13.3, 13.3

USERS tablespace, 3.2.3, 4.2.3 users, multiple

security strategy, 13.2.2

using

web service with a secure website, 7.2.8

utilities

Metadata Loader, 12.5

V

validation

errors, A.2

validation rules for metadata import, 12.2.4 virtual memory

errors, A.3

W

Warehouse Builder

frozen, A.4

hanging, A.4

installing, 2.4.1

passwords, 13.10

web service

testing, 7.2.8

web service with secure website, 7.2.8 web.xml, 7.1.1 wfinstall.bat, 7.5 wfinstall.csh, 7.5 wf.log, 7.5 workflow account, 7.5 Workflow Client, 7.5 Workflow Configuration Assistant, 7.5 workflow password, 7.5 Workflow Proxy User, 7.5 workspace, 3.2.1, 4.2.1

creating, 3.3, 4.3

Linux, 4.3

Windows, 3.3

deleting, 5.3 dropping, 5.3 managing, 3.3, 4.3 workspace owner

deleting, 5.3

workspace user

adding, 3.3, 4.3

deleting, 5.2

managing, 5.2

unregistering, 5.2

Copyright © 2000, 2011, Oracle and/or its affiliates. All rights reserved.