This chapter includes the following sections:
The Oracle BI Presentation Catalog stores the content that users create in a directory structure of individual files.
This content includes folders, shortcuts, Oracle BI EE objects (such as analyses, filters, prompts, and dashboards), and Oracle BI Publisher objects (such as reports and templates).
This section contains the following topics:
The figure below shows sample objects in the catalog, as seen in Presentation Services.
Guidelines for Object Names
Each object in the catalog is stored in its own file. For example, an analysis called Analysis 1 is stored in a file named Analysis1. The object name that is visible to users, such as Analysis 1, is referred to as the logical object name.
The following list provides guidelines for object names:
No restrictions exist on which characters are allowed in the logical name of an object in the catalog, provided that the characters are valid Unicode characters. The following are valid logical names:
Hello World Profit / Loss % Sales * $ Cost ~~ $ "Expense"?
The length of the logical object name must not exceed 256 Unicode characters.
The length of the logical path name for an object must not exceed 16000 Unicode characters.
The number of directory segments in a logical path name for an object must be not exceed 255 segments.
For example, a directory with a name such as /n1/n2/n3/n4/…./n253/n254/n255 is acceptable, while a name such as /n1/n2/n3/n4/…./n254/n255/n256 is unacceptable.
When you pass the path name of an object using SOAP, you must escape the following characters:
Forward slash (/) Backward slash (\) Tilde (~) Asterisk (*) Question mark (?)
The following logical path names are all valid:
/shared/test/Hello World /shared/test/Profit \/ Loss /shared/test/% Sales \* $ Cost \~\~ $ "Expense"\?
Use care when building a catalog path. It is very common to see code that assumes the forward slash (/) is always a path separator. Always verify your path code with an object name such as "Profit / Loss".
When you pass a catalog search filter using SOAP, you must escape the following characters:
Forward slash (/) Backward slash (\) Tilde (~) Asterisk (*) Question mark (?) Caret (^) Dollar sign (?)
The following search filters are all valid:
Hello World Profit \/ Loss % Sales \* \$ Cost \~\~ \$ "Expense"\?
Attribute Files for Objects
Each object has a corresponding attribute file. For example, the analysis called Analysis1 would have a corresponding attribute file named Analysis1.atr. The attribute file contains the object's full name, access control list (ACL), description, and so on. To access an object in the catalog, users must have appropriate ACL entries for that object. All objects in the catalog use ACL entries.
Lock Files for Objects
To guarantee that only one user can write to a file at one time, a lock file is created when an object is being written to. On rare occasions (for example, after a power outage), temporary lock files in the catalog might not be removed completely. If Presentation Services reports of such a lock file, then you must delete it manually.
This section describes the guidelines for working with objects in catalogs in file systems.
Handling Users of the Catalog
The catalog is designed to scale to thousands of concurrent users. To achieve this scaling, the catalog adheres to the following guidelines:
The average user typically only reads from the catalog and rarely, if ever, writes to it. Each user is constantly and automatically updating his or her Most Recently Used file, but each user's "read" operations still far outweigh the user's "writes" operations. Therefore, the read-to-write ratio is typically at least 100 to 1.
While a locking mechanism guarantees that only one user can write to an object at a time, it is rare for multiple users to attempt to write simultaneously to the same object. A feature called "lazy locking" enables users to continue reading an object even when another user is updating that object.
Modern file systems cache "small" files directly inside the directory record, such that reading any information on a directory simultaneously loads all small files directly into the operating system's memory cache. Therefore, it is good practice to keep files in the catalog "small," especially the frequently "read" .atr metadata files. When these metadata files remain small, then all the .atr files in a directory are loaded into memory with one physical hard disk read. Every file that exceeds the "small" threshold adds another physical hard disk read, which can cause a 100% degradation for each large file. In other words, use care when considering storing arbitrary "Properties" in .atr files.
Reading an object's .atr metadata file using NFS is far slower than reading it directly from a local disk. For this reason, Presentation Services additionally caches all .atr files internally. This cache can become briefly "stale" when another node in the cluster writes data to the file that is newer than the data that is cached by the current node. Therefore, all nodes are refreshed according to the MaxAgeMinutes element in the instanceconfig.xml, whose default for a cluster is 5 minutes. This default setting commonly achieves the best trade-off between the possibility of stale data and the known performance impact. (The default for an environment without clusters is 60 minutes.)
You can modify the MaxAgeMinutes element for your system. Its parent elements are Cache and CatalogAttributes.
Handling Heterogeneous Nodes
To allow heterogeneous nodes in a cluster, the catalog adheres to the following guidelines:
The maximum length for the name of an object on disk is 256 bytes, which is 64 Unicode characters. The logical name is restricted to 256 Unicode characters. To adhere to this restriction, logical names greater than 32 characters are hashed.
The maximum length for the name of a path on disk is 32KB, which is 8000 Unicode characters. The logical path is restricted to 16000 Unicode characters.
All path names on disk are all lowercase. The logical path name allows mixed case, but is still case-insensitive.
Certain characters are not allowed for path names on disk, while the logical path name allows all characters. For example, Windows systems disallow certain characters such as the colon (:), so those characters are mapped using standard HTML escape sequences. For example, the period character (.) becomes "%2e".
Certain file names are not allowed on disk, while the logical object name has no restrictions. For example, Windows systems disallow certain file names such as COM, so those names are mapped using standard HTML escape sequences. For example, "com" becomes "co%6d".
Handling Catalog Files on Various Platforms
Keep the following points in mind when handling catalog files on various platforms:
For UNIX Platforms: UNIX kernels must commonly be configured to allow more than 4000 subdirectories per directory. See Manually Changing Configuration Settings for the Catalog for information on the HashUserHomeDirectories element.
For Windows Platforms:
When users want to navigate catalog files using a tool such as Microsoft Windows Explorer, then they want the catalog structure based on a short path name such as c:/obi/demo, rather than the long default path name. Note that such navigation is not recommended.
FAT is not supported, and NTFS is required.
Performance on Windows platforms degrades noticeably when more than 8000 files exist in a single directory. Because each catalog object has two files (the data file and the .atr metadata file), it is strongly recommended that you not store more than 4000 catalog objects in a single directory.
Windows Explorer does not handle long path names properly, and it is recommended to not use Windows Explorer to navigate the internal structure of the catalog. While the file system can handle path names as large as 32KB and Presentation Services is not negatively affected, you cannot use Windows Explorer with any path name that is longer than approximately 2KB.
Because a single Unicode character can require as many as 4 bytes, you might be unable to use Windows Explorer with path names of only 500 Unicode characters. This limitation does not affect Presentation Services. Because of this limitation, place the catalog in a top-level directory, such as c:\mycatalog\sales.
Known Issues with Catalog Files
The following issues are known when working with catalog files:
Various third-party FTP programs have issues handling '%' escape sequences, which often results in a renamed file that is doubly escaped. For example, a file that is named sa%2epaint (whose logical name is SA.Paint) is incorrectly renamed to sa%252epaint (whose logical name is SA%2ePaint).
Avoid using an FTP program directly against a catalog. Instead, download and use the 7-Zip utility to compress the catalog files, then use an FTP program to transfer the resulting compressed file.
Refer to the topics below for information on maintaining a catalog.
You modify settings manually using various elements in the instanceconfig.xml file to change these settings.
HashUserHomeDirectories: Specifies the hashing of directories. If you have more than 4000 catalog users or if you intend to have more than 4000 catalog users in the future, then you must turn on the hashing of users' home directories to address a file system limitation. To do so, set the HashUserHomeDirectories element to 2 from its default value of 0. When this element is turned on, for example, the default name for user Steve's home directory would become /users/st/steve.
Keep the following points in mind:
Hashing is not typically needed for modern operating systems that use modern file systems (for example, ext4, ZFS, ntfs); however, it may still be useful for performance when your user base exceeds approximately 4,000 users.
Oracle recommends that you hash a catalog at creation time; however, there are circumstance that require hashing the catalog after it is in use. Take a backup and run the following command for more information:
runcat.sh -cmd rehash -help
runcat.cmd -cmd rehash -help
In general, do not set the HashUserHomeDirectories element to a value greater than 2, because a higher setting negates the effectiveness of hashing.
Include only one Catalog element in the instanceconfig.xml file or unexpected results might occur. Unless expressly noted, include most nodes in an XML document only once.
<ServerInstance> <Catalog> <HashUserHomeDirectories>2</HashUserHomeDirectories> </Catalog> </ServerInstance>
You can deploy catalogs and simple objects (for example, a dashboard with privileges) to a production environment from a test environment, as described in the following sections:
You deploy a Catalog to production using BAR files.
You can deploy objects (for example, a dashboard with privileges) to a production environment from a test environment.
(Optional) If you are deploying a catalog object to a new production environment.
Archive the catalog object in the test environment and unarchive it in the production environment as follows:
Archive the catalog object in the test environment using one of the following:
Oracle BI Presentation Services.
Copy the archived file to the production computer.
On the production computer, unarchive the object.
For information about how to unarchive an object, see Archiving and Unarchiving Using Catalog Manager.
Set the permissions on the object as appropriate.
(Optional) If you are deploying the catalog to an existing production environment.
Copy and paste new or updated objects from the test catalog into the production catalog as follows:
Open two Catalog Manager windows: one with the test catalog, and another with the production catalog.
Selectively copy and paste the folders from the test catalog into the production catalog.
If you copy and paste folders where the same content has been changed in the test or production environments, then test content overwrites the production content.
If you upgrade to a newer version of Oracle Business Intelligence or install a patch and work with objects in the catalog, then you might notice that certain objects are not being accessed as quickly as in the previous release.
This change can occur if objects are not upgraded properly. You can confirm the need to update by viewing the metrics in Fusion Middleware Control. In the Catalog folder, find a metric called "Reads Needing Upgrade" with description "The number of objects read that required upgrading." If the number is large, then you can resolve this issue by updating objects in the catalog using the Administration page in Presentation Services.
You upgrade to new versions of Oracle Business Intelligence by following the instructions in the Upgrade Guide for Oracle Business Intelligence. To upgrade Catalog objects follow Task 5: Upgrade the Oracle BI Repository and Catalog in Upgrade Guide for Oracle Business Intelligence. Oracle recommends that you upgrade when Presentation Services is not running. If you suspect that the upgrading of objects was not performed thoroughly during the upgrade process, then you can update the objects yourself using the Administration page. The advantage of this approach is that Presentation Services can stay up and running during the update.
Bear the following points in mind as you prepare to update objects:
If you are performing a rolling upgrade of machines in a cluster, then do not use this option or the UpgradeAndExit configuration setting until all machines in the cluster are upgraded.
Use this option on only one node in a cluster at a time.
Click the other links on the page to see which objects were updated and which were not. You can view the log files for details on objects that were not updated.
Catalog Manager is a tool that lets you perform online and offline management of Oracle BI Presentation Catalogs. Install Catalog Manager on a secure computer that is accessible only to Oracle BI Administrators.
Uses for Catalog Manager
You can use Catalog Manager to:
Manage folders, shortcuts, global variables, and objects (analyses, filters, prompts, dashboards, and so on). For example, you can rename and delete objects, and you can move and copy objects within and between catalogs.
View and edit catalog objects in Extensible Markup Language (XML).
Preview objects, such as analyses and prompts.
Search for and replace catalog text.
Search for catalog objects.
Create analyses to display catalog data.
Validate the catalog.
Localize captions. See Localizing Oracle BI Presentation Catalog Captions.
Many of the operations that you can perform in Catalog Manager can also be performed through the Catalog page in Oracle BI Presentation Services. See Managing Objects in the Oracle BI Presentation Catalog in User's Guide for Oracle Business Intelligence Enterprise Edition.
Guidelines for Working with Catalog Manager
Follow these guidelines when working with Catalog Manager:
Always make backup copies of the Oracle BI Presentation Catalogs that you are working with.
Be sure of changes that you plan to make. Catalog Manager commits changes immediately. There is no undo function nor are there any error messages to tell you that a particular change does not display well to users. However, if you do make any unwanted changes, then you can revert to your latest saved backup.
Do not copy and paste catalog contents into email, as this is not supported.
Tips for Working with Catalog Manager
As you work with Catalog Manager, keep the following tips in mind:
While working in online mode, you can paste catalog contents into or out of a read-only folder by turning off the read-only property of the folder tree before copying, then re-apply the read-only attribute after pasting.
You cannot copy, archive, or drag files from the
/system/security directory in the Catalog Manager.
Some keyboard shortcuts might not work properly.
Even if a resize indicator is not shown, Catalog Manager panes might still be resizable.
You can use Catalog Manager in languages other than English. See Setting the Current Locale in Catalog Manager.
Learn more about starting catalog manager and opening catalogs in these topics.
This section describes the following topics:
You must use these components to run Catalog Manager.
The following list describes the requirements for running Catalog Manager:
Graphical User Interface — You can invoke the user interface on the following platforms:
Command Line Utility — You can invoke the command line utility on supported platforms for Oracle Business Intelligence such as Windows, Linux, IBM-AIX, Sun Solaris, and HP-UX. Enter a command such as the following one on Linux for assistance in using the command line utility:
You can start the user interface for Catalog Manager using menu options on Windows or a command on Windows or Linux.
Using the command line, change to the following directory:
then run the appropriate script:
runcat.cmd (on Windows)
runcat.sh (on Linux)
The following illustration shows sample objects in the Catalog Manager for Windows platforms.
You must start the Catalog Manager in a graphical user interface xterm on Linux systems.
Examples of xterms are a native gnome, kde console, VNC, or a local x-server such as Xming, Tarantella, Hummingbird Exceed, or Citrix. (These examples do not constitute a statement of certification or support.) You cannot start the graphical user interface for Catalog Manager using an ASCII text terminal, such as PuTTy or FSecure or a command-line SSH.
If the Catalog Manager does not start, then verify the following:
That you can run a native application such as xclock or xeyes.
That you can start Catalog Manager with a native console or with VNC. Sometimes operating system administrators can lock X-Windows.
That you can run the following command, which allows all xterm connections:
That you can run Catalog Manager from the command line with debugging enabled to see if any additional output is produced, using the following command:
./runcat.sh -consoleLog -noExit
That you can use an operating system utility such as
strace to trace the execution of the
runcat.sh command and see if any error messages are generated, such as those relating to libraries or files being unable to open. You can use the Eclipse Java plug-in that requires the standard widget toolkit (SWT), which in turn requires GTK (Gimp Toolkit) to be installed. Enter the following command:
strace -aef -o ./runcat_trace.txt runcat.sh
You can open a catalog in one of two modes — online or offline. Both modes can operate against an actual production catalog, with no need for any downtime.
In online mode, you connect to a catalog on a running web server. In this mode your permissions are applied, you can select a locale, and you can see the effects of any localization on the catalog. You can see only those objects for which you have the appropriate permissions. Both Presentation Services and the web server must be running for you to open catalogs in online mode.
Use online mode when you want to make minor incremental changes or additions to the catalog, such as changes to permissions, updates to a single object, or migration of new objects to a production environment.
In offline mode, you connect to a local file system. In this mode, you are logged in as a super user or system user, and no permissions are applied. You can see all objects in the catalog.
Generally, working in offline mode is faster than working in online mode. This is because you are accessing, creating, and updating the individual files directly, and the catalog does not have to communicate with Presentation Services as it does when you are working in online mode.
Use offline mode when you want to make catalog-wide changes, such as globally renaming objects or moving multiple objects for reorganization, as described in the following procedure.
Place Presentation Services in Maintenance Mode.
In a clustered environment, you can place any instance of Presentation Services in Maintenance Mode and within a few minutes, all other instances in the cluster automatically go into Maintenance Mode too. In a clustered environment only, wait a few minutes before performing the tasks for which you placed Presentation Services into Maintenance Mode.
Back up the catalog by using the 7-Zip utility to create a compressed file for it.
In Catalog Manager, open the catalog in offline mode, as described in Opening an Oracle BI Presentation Catalog.
Make the systemwide change.
Back up the catalog again.
Take Presentation Services out of Maintenance Mode.
In a clustered environment, you can take any instance of Presentation Services out of Maintenance Mode and within a few minutes, all other instances in the cluster automatically go out of Maintenance Mode too. So in a clustered environment only, a few minutes are required before users can resume editing catalog content.
Presentation Services Maintenance Mode
Maintenance Mode is set on the Presentation Services Administration page. When you put Presentation Services into Maintenance Mode, you make the catalog read-only so that users cannot modify its contents. Users can continue to perform tasks that do not involve writing to the catalog such as viewing existing objects (for example, dashboards and analyses). Tasks such as updating a user's "most recently used" list are not available.
When Presentation Services is in Maintenance Mode, a lock file that is named
root_maintenancemode.lck is created in the directory for the catalog. (On UNIX systems, that file is a link to a file that has a name such as
root_maintenancemode_number.lck, meaning both files make up the lock file.) If you create a zip file for the catalog when Presentation Services is in Maintenance Mode, then the zip file includes the lock file. If you extract the contents of the zip file and open the catalog, then Presentation Services is placed in Maintenance Mode.
Unlike previous releases, if you put Presentation Services into Maintenance Mode and Presentation Services is restarted, then Presentation Services starts with Maintenance Mode still turned on.
Many of the operations that you can perform using Catalog Manager are available in both online mode and offline mode. A few operations are available in only one mode or the other.
Generally, the operations available in:
Online mode includes read-only operations and write operations that do not affect the entire catalog, such as setting permissions for an object.
Offline mode includes most of the operations available in online mode and write functions that affect the entire catalog.
You can perform the following operations in online and offline modes (or as stated), as follows:
Copying objects for another catalog.
Pasting objects from another catalog.
Creating shortcuts of objects.
Renaming objects without reference updates.
Renaming objects with reference updates. (This feature is known as Smart Rename and is available in both modes. In offline mode, you can rename all objects. In online mode, you might be unable to rename certain objects, depending on your permissions.)
Refreshing the Catalog Manager workspace.
Setting permissions for objects.
Working with properties of objects.
Managing the view of the workspace.
Searching for objects.
Searching for and replacing catalog text. (This feature is available in both modes. In offline mode, you can replace all objects. In online mode, you might be unable to replace certain objects, depending on your permissions.)
Creating reports to display Catalog Manager data.
Setting browser preference.
Previewing objects (available in online mode only).
Exporting captions for localization purposes.
Follow the steps below to open an Oracle BI Presentation Catalog.
Type — Select the mode (online or offline) in which to open the catalog
Path — If you are opening the catalog in offline mode, then enter the path to the catalog folder on the local file system, for example:
Click Browse to display a dialog for locating the catalog.
where SDD is the Singleton Data Directory for example,
DOMAIN_HOME/bidata. See Key Directories in Oracle Business Intelligence.
URL — If you are opening the catalog in online mode, then enter the URL to Oracle BI Presentation Services, for example:
User — If you are opening the catalog in online mode, then enter the user name for the host URL (disabled in offline mode).
Password — If you are opening the catalog in online mode, then enter the password for the host URL (disabled in offline mode).
Locale — Select the locale to use for user interface elements in Catalog Manager and for objects in the catalog, when opening the catalog in online mode.
Read-Only — Select this field to open the catalog in read-only mode (disabled in offline mode).
When specifying the URL for the catalog in online mode, ensure that you specify
https rather than
http, for increased security. If you specify
http, then you see a message box after closing the Open Catalog dialog that prompts you to verify the opening of the catalog using an unsecured connection. To use
https when opening catalogs, you must configure Oracle BI EE for Secure Socket Layer communication, as described in Configuring SSL in Oracle Business Intelligence in Security Guide for Oracle Business Intelligence Enterprise Edition.
The Catalog Manager workspace provides resources for maintaining user content.
This section provides the following topics on the workspace for Catalog Manager:
The Catalog Manager workspace enables you to view and work with catalog objects.
It displays the following folders for an open catalog:
The shared folder — Contains content that is shared among catalog users. This includes the preconfigured dashboards and analyses that are distributed with prebuilt applications, and other objects such as shared filters.
The system folder — Contains administrative elements of Presentation Services. Some of these elements are distributed with the product, and others are configured by you as the administrator, such as privileges. Avoid modifying any files in this folder. Presentation Services uses these files internally and modifying them might cause unexpected results.
The users folder — Contains content that catalog users with the appropriate permissions have saved to their personal folders, such as individual analyses.
The Catalog Manager workspace provides a variety of tools for working with data.
Catalog Manager consists of the following main components:
Menu bar — Lets you access the following menus:
File — Provides options that let you open and close catalogs, exit Catalog Manager, and so on.
Edit — Provides options that let you manage catalog objects, such as Cut, Copy, Permissions, and so on. (Many of these options are also available on the right-mouse menu.)
View — Provides options to manage the view of the Catalog Manager workspace, such as Show Tree, Show Job Status, and so on.
Tools — Provides options that let you manage catalogs, such as XML Search and Replace, Create Report, and so on.
Help — Provides options to access the Oracle BI Enterprise Edition website and to display information about Catalog Manager.
Toolbar — Provides quick access to commonly used options, such as Cut, Copy, Paste, and so on.
Tree pane — Displays catalog folders. The pane also displays objects but only if the Show Objects in Tree option on the View menu is selected.
Table pane — Displays catalog folders and objects. It consists of:
The navigation bar, where you can move to the catalog object to work with by typing its path name.
These columns: Name, Type, Owner, My Permissions, Attributes, Date Created, and Last Modified. Click the column name to sort by that value, such as by type.
The Type column identifies the type of object. Objects that are identified as "unknown file" are generally internally used objects, and their type is not exposed in Catalog Manager.
Right-mouse menu — Provides options that let you manage catalog objects, such as Rename, Properties, Permissions, and so on. (Many of these options are also available on the Edit menu.)
You can manage what you view in the Catalog Manager. For example, you can show objects in the Tree pane or show job statuses.
Show Tree — Displays the Tree pane, if you previously had closed it.
Show Table — Displays the Table pane, if you previously had closed it.
Show Job Status — Displays the Background Job Status pane, where you can view the progress of processes that you have run, such as Search and Replace, Smart Rename, and so on. You can also remove all finished jobs and set progress preferences using the icons in the upper-right corner of the pane.
Show Objects in Tree — Displays objects (that is, analyses, filters, and so on) in addition to folders in the Tree pane.
Refresh — Refreshes the objects that are displayed in the Tree and Table panes. (You might want to refresh the data, for example, if someone else makes changes to the catalog while you are working with it and you want to see the changes.)
You can alter objects in Catalog Manager in several ways.
This section provides the following information about working with objects:
In the Catalog page of Presentation Services, you can view folders and contents including hidden objects. You can create, rename, copy, move, and delete folders and contents. See Managing Objects in the Oracle BI Presentation Catalog in User's Guide for Oracle Business Intelligence Enterprise Edition.
Note:Changes made in the Presentation layer of the Oracle BI Administration Tool can affect analyses and dashboards based on those tables and columns. You can use Catalog Manager to keep the catalog synchronized with these changes in the Presentation layer.
You can search for objects in the catalog using the Search function.
For example, you might want to search for all objects that have a property with the value of "administrator."
When you search, you can limit the search by:
Case Sensitive — Select this check box to apply case sensitivity to the search criteria. The default value is unchecked.
Name — Limits the search to the names of objects.
Description — Limits the search to the Description property.
Property values — Limits the search to the values of properties.
Owner — Limits the search to the owners of objects.
XML — Limits the search to XML.
Object type — Searches for all types of objects or limits the search to a specific type of object that you specify (for example, analyses, filters, agents, dashboard prompts, dashboard pages).
Date — Limits the search to objects that were created on the dates that you specify or to objects that were last modified on the dates that you specify.
Use the following steps to search for an object.
Tip:When you have finished searching, click Explore the entire catalog tree on the toolbar to return to the Tree and Table panes.
You can copy and paste objects within a single catalog.
You can also copy objects from one catalog and paste them into another catalog.
You can execute and use copying and pasting in several ways.
Use the following tips as you copy and paste objects:
You can copy and paste objects using the following methods:
Menu options, as described in Copying and Pasting Objects Between Catalogs Using Menus.
Drag and drop, to copy objects between two catalogs and within the same catalog. Drag and drop always makes a copy of the dragged objects, even when performing a drag and drop within a single catalog.
Archive and unarchive, as described in Archiving and Unarchiving Using Catalog Manager. When you archive, you create a file that you can save for later use. The unarchiving process automatically overwrites any files without providing the opportunity to specify that certain files not be overwritten.
Catalogs are structured in hierarchical folders. When copying or merging objects, remember to also copy any objects that are associated with them, such as dashboard folders, shortcuts, and analyses. URL paths in external applications can be reestablished after a copy or merge operation if the entire folder path is not copied, for example, if added to the dashboard as a shortcut or text.
Most often, you can simply copy and paste objects as needed. If required, you can set advanced options that affect the objects that you are pasting. See Advanced Options for Pasting Objects.
The following procedure describes how to copy and paste objects between two catalogs using menu options.
If the two catalogs have the same name, then you might want to rename one of the catalogs before opening it to help distinguish between the two catalogs as you work. Both catalogs must be the same version 11.1.1 (or later).
You can set advanced options in the Preferences dialog for pasting objects that you have copied, as described in the following sections:
You must set the advanced options in the Preferences dialog before you begin the copy and paste operation, for them to take effect.
The Preferences dialog contains a number of options in the Paste Overwrite area.
Force — Pastes all files, overwriting even those that have the read-only attribute set.
All — Pastes all possible files, overwriting only those that do not have the read-only attribute set. (Default)
Old — Pastes all possible files, but does not overwrite any existing files unless they are older than the source.
None — Pastes all possible files, but does not overwrite any existing files.
Consider the following example of pasting with overwrite options set. Suppose that the /users/joe folder contains the following analyses:
Suppose that the /users/sue folder contains the following analyses, but no Analysis C
Suppose that Sue copies the A, B, and C Analyses from the /users/joe folder and pastes them to the /users/sue folder. If the Paste Overwrite option is set to:
None, then Sue keeps her A and B Analyses, and Joe's analyses are ignored. Sue gets a copy of Analysis C.
All, then Sue's A and B Analyses are overwritten with Joe's, and Sue gets a copy of Analysis C.
Old, then Sue keeps her A Analysis (Sue's A Analyses is not "old"), Sue's B Analysis gets overwritten by Joe's analysis (Sue's B Analysis was "old"), and Sue gets a copy of Analysis C.
The Preferences dialog contains a number of options in the Paste ACL area.
Inherit — Inherits the object's permissions (ACL) from its new parent folder. (Default)
Preserve — Preserves the object's permissions (ACL) as it was in the original, mapping accounts as necessary.
Preserve Only Groups — Same as Preserve, but applies to group accounts and Application Roles, not to user accounts. This is for a development to production environment in which a customer might use the same groups (such as Sales and Marketing) in both development and production. However, the users in each group might be very different, such as TestUserA and TestAdminB in development and Steve and Sue in production.
Create — Preserves the object's permissions (ACL) as it was in the original, creating and mapping accounts as necessary, depending on the mode and type of owner, as described in the following list:
Online mode — In online mode, Catalog Manager is communicating with the back-end security server. Catalog Manager knows about the users and application roles from that server and can usually paste a copied object with the appropriate user name or role. While pasting objects, keep in mind that you might lack appropriate permissions to create accounts for certain objects.
Offline mode — In offline mode, Catalog Manager has no connection with the back-end security server, so it is unaware of users and application roles that are stored there, unless their names are available in the cache for the catalog. If the name of the user or role for a copied object is not available in the cache, then Catalog Manager cannot paste the copied object with that name or role. Instead, the pasted object inherits its owner from its new parent folder, which is similar to the Inherit option.
This feature is used in applications whose administrators create accounts in a staging area before moving the users to the production environment.
If you have the appropriate permissions, then you can select a newly pasted object and set ownership recursively to the appropriate user.
Consider the following example of pasting with ACL options set. Suppose that Steve owns the /users/steve/MyFavReport folder and has permissions (ACL) "all users can read/execute, steve has full control". Joe (who has some administration privileges) logs in and copies MyFavReport, pasting it to /users/sue (which is owned by "administrator", with permissions "admins have full control, sue has full control").
If Joe sets the Paste ACL option to:
Inherit, then the /users/sue/MyFavReport folder is owned by Joe with whatever permissions are set on the /users/sue folder (that is, "admins have full control, sue has full control").
Preserve, then the /users/sue/MyFavReport folder is owned by Joe with whatever permissions were set on the /users/steve/MyFavReport folder (that is, "all users can read/execute, steve has full control"). If Joe pastes in a second Catalog Manager and if "steve" does not exist in this Catalog, then the permissions for Steve are discarded. If "steve" exists but has a different user ID, then Steve's user ID is mapped to the new one.
Create in online mode, then the /users/sue/MyFavReport folder is owned by Joe with whatever permissions were set on the /users/steve/MyFavReport folder (that is, "all users can read/execute, Steve has full control"). If Joe pastes in a second Catalog Manager and if "steve" does not exist in this catalog, then the owner is inherited from the parent folder. (The Create option is deprecated in Release 11g as it applies only to Catalog groups.)
You can rename objects in the catalog.
This can be useful when you are migrating from a test environment to a production environment.
There are two ways to rename an object:
Rename without reference updates — Renames the object and preserves the references to the original name that other catalog objects might have.
Rename with reference updates — Renames the object and changes references that other objects might have to the new name (that is, original name references are not preserved). This feature is also known as Smart Rename. You can open the catalog in either offline or online mode. In offline mode, you can rename all objects. In online mode, you might be unable to rename certain objects, depending on your permissions.
Caution:Keep the following points in mind when renaming objects:
You cannot rename a user account in the catalog. If you rename a user's home directory, then you do not rename that user and you might see unexpected results.
The catalog contains several reserved names of objects. Rename only your own objects, not those that Presentation Services creates internally. For example, do not rename the _portal directory in your home directory, because then you cannot see "My Dashboard".
Use the following steps to rename an object without reference updates.
In Catalog Manager, open the catalog.
Navigate to the object to be renamed.
Right-click the object in the Name column and select Rename.
Type a new name for the object.
To rename an object with reference updates:
A progress bar in the lower-right corner of the window shows the progress of the reference updates.
You can work with object properties through the Catalog Manager.
Using the Properties option of Catalog Manager, you can:
Create, view, edit, and delete the properties of catalog objects.
Change attributes of catalog objects to hide them from display in Oracle Business Intelligence.
In Catalog Manager, open the catalog.
Navigate to the object.
Right-click the object in the Name column and select Properties.
Perform the necessary tasks:
If you have the appropriate permissions, then select the appropriate owner for the object in the Owner list.
The Owner list includes the name that you used to log in to Catalog Manager. You can use this list to select yourself as the owner of the object.
See Assigning Ownership of Objects in User's Guide for Oracle Business Intelligence Enterprise Edition for information on taking ownership of objects.
To change the attribute of an object, select either Read-Only or Hidden, if appropriate. A hidden object is not visible in Oracle Business Intelligence.
The System option indicates that the object is maintained internally and should not be altered.
To create, edit, or delete a property, use the New, Edit, or Delete button as appropriate.
Note:The New button is used to create a property. Use it only if instructed to do so by Oracle Support Services.
You can select multiple objects and update their properties or permissions simultaneously. If any of the selected objects are a folder, then you can also apply those changes recursively to all the objects in that folder's tree structure.
For example, you can set all files in the /shared/DontTouch directory to be Read-Only. Right-click the DontTouch directory and select Properties. In the Properties dialog, select the Read-Only option, select the Apply Recursively option, and click OK. You can also select Apply Recursively to take ownership of an object and all its sub-objects.
Permissions are used to control access to catalog objects.
The Permissions dialog displays these two lists:
Users and Application Roles (Explicit Permissions) — Shows the users, groups, and application roles that have explicit permissions granted to this object.
Additional Users and Application Roles — Shows the users, groups, and application roles that have access granted through group inheritance, and users, groups, and application roles that have no access to the request.
For details on how permissions and privileges are assigned in Presentation Services, see Managing Security for Dashboards and Analyses in Security Guide for Oracle Business Intelligence Enterprise Edition.
Enter filter criteria in the field next to the List button (case insensitive) to search by name.
To enter partial filter criteria, use the asterisk (*) symbol. For example, enter bi* to display users or groups beginning with bi, BI, bI, and Bi.
Select a value from the list, to restrict what accounts to search for.
Available values are: All, User, or Application Role.
For details on what each permission means, see Permission Definitionsin User's Guide for Oracle Business Intelligence Enterprise Edition.
Replace All — Replaces the existing ACL with what is currently in the dialog.
Replace Listed — Changes only the accounts currently displayed in the dialog and leaves others unchanged.
Remove Listed — Removes only the accounts currently displayed and leaves others unchanged.
Note:If you move a user or group from the Users and groups (Explicit Permissions) list to the Additional Users and Application Roles list, then the user or group privileges are reset to No Access. To move a user or group from one list to another, highlight it and click the right or left-arrow button, as appropriate.
See Security Guide for Oracle Business Intelligence Enterprise Edition for more information about permissions and groups and users.
You can preview objects, such as analyses or prompts, from Catalog Manager in online mode. If you are going to preview objects from Catalog Manager, then you must identify the default browser in which to display these objects.
In Catalog Manager, from the Tools menu, select Preferences.
In the Select Web Browser to use for report previews field, select the browser that is the same one that you have set to be the default browser for your operating system. You can click the Browse button in which you can select the executable file for the appropriate browser.
To preview an object:
The catalog is a dynamic component which requires maintenance. Over time, inconsistencies can develop in the catalog as links are broken, users are deleted, or NFS file system issues are encountered. These inconsistencies can eventually lead to incorrect behavior, such as the inability to edit an agent's recipient list. You can periodically take the production system offline and validate the catalog, to be informed of and to take corrective action on inconsistencies.
The validation process performs the following tasks:
Ensures that each object in the catalog is larger than zero bytes.
Ensures that each item in the catalog has a valid corresponding
Ensures that each link in the catalog is valid.
Ensures that all XML objects in the catalog pass schema validation.
Attempts to repair object names that were damaged by ftp programs.
PrerequisitesBefore validating the catalog in a clustered environment, do one of the following:
Shut down the Presentation Services cluster and run the validation directly against the cluster's catalog.
Make a copy of the cluster's catalog and run the validation against that copy.
Before using the 7-Zip utility to make a copy of a catalog, first shut down all nodes in the Presentation Services cluster or put all nodes in that cluster into Maintenance Mode (which is the recommended approach).
Be aware that any changes that are made to the catalog online concurrently to the validation process are not included in the validation.
While backing up the catalog is always good practice, there is no practical difference between running validate against the catalog directly versus running the validation on a backup copy.
Validating the Catalog
Catalog validation can only be completed using the command line, not the Catalog Manager user interface.
Open the catalog in offline mode as described in Understanding the Two Catalog Modes.
runcat.cmd -cmd validate
runcat.sh -cmd validate
For a list of parameters used by the command and information on how to use them, append
-help to the command.
Catalog Manager provides the ability to view and to edit the XML description of catalog objects such as analyses, dashboards, filters, and so on.
While viewing the XML code is acceptable, editing the code is not recommended.
Caution:If you edit the XML code, then you change the representation of the object in the catalog. Editing the XML code for catalog objects in any directory is not recommended and can produce unexpected results.
If you want to edit the XML for an analysis, then use the information in Examining the Logical SQL Statements for Analysesin User's Guide for Oracle Business Intelligence Enterprise Edition.
In Catalog Manager, open the catalog.
Navigate to the object.
Right-click the object in the Name column and select Properties.
Click Edit XML.
When you have finished viewing the XML definition, click Cancel.
Click OK in the Properties dialog.
The illustration shows sample XML code in Catalog Manager for an object.
To edit the XML description of an object, which is not recommended:
Note:When you edit the XML description of an object, the catalog checks only that the XML is well-formed; it does not check for any other errors.
You can search for specific text in the catalog and replace it with other text using Catalog Manager.
You can open the catalog in either online or offline mode. In offline mode, you can replace all objects. In online mode, you might be unable to replace certain objects, depending on your permissions.
Specifically, you can search for and replace:
A simple text string using a dialog, as described in Searching for and Replacing a Simple Catalog Text String.
For example, suppose that an object contains the string "My Misspeled Wirds." You can use Catalog Manager to search and replace that string with the proper text of "My Misspelled Words."
Multiple or complex text strings all at the same time using an XML file, as described in Searching for and Replacing Multiple Catalog Text Strings.
For example, suppose that the administrator renames a subject area, a table, or column in the repository file. The table "Sales" might be renamed "MySales." You can use Catalog Manager to search and replace all uses of that object throughout the catalog.
You can search for a simple text string in the catalog and replace it with other text.
You can perform more powerful search and replace operations on multiple catalog text strings all at the same time by importing a XML file that identifies each text string to search for and replace.
In the search and replace XML file, you use an action element to identify each text string to search for and replace.
The action elements are contained in a commands element. The action element has the following attributes:
command — Specifies the text to replace. The valid value is:
textReplace — Replaces all the text that matches in an XML file, such as a column name.
oldValue — Specifies the text string to search for.
When you specify this attribute for the textReplace command for the search and replace XML file, you must use the full Java regex syntax, which is not like a normal string. To replace a string, you must do the following:
Escape any special Java regex characters (such as brackets, parentheses, dollar signs, and carets).
Escape any special "normal" string characters (such as back slashes and quotes).
Because you are working in an XML file, escape any special HTML characters (such as quotes and ampersands).
The full Java regex syntax is described in the following document:
The following table provides sample strings for use with the regex syntax in search criteria.
|Search String Entered||Result|
Adds wildcards before and after your search string (for example, *a*), enabling the search to return results that contain the letter "a".
Adds a wildcard after your search string (for example, a* ), enabling the search to return results that begin with the letter "a".
Adds a wildcard before your search string (for example, *a ), enabling the search to return results that end with the character "a".
Searches explicitly for strings containing a character followed by an asterisk (*) for example, "a*".
Use a question mark (?) with a character and an asterisk (*) to return zero (0) or more occurrences of a character. For example ?a* returns zero or more occurrences of the character "a".
newValue — Specifies the replacement text.
ignoreCase — Ignores case when set to true, but becomes case-sensitive when set to false. The default value is false.
The following is a partial example of an XML file for searching for and replacing a text string.
<?xml version="1.0" encoding="utf-8"?> <actions> <action command="textReplace" oldValue="boots" newValue="HoleyShoes" ignoreCase="true"/> </actions>
Use the following procedure to search for and replace multiple catalog text strings all at the same time.
You can create reports to display catalog data for all catalog object types. You can either display the report on the screen or save it to a file.
When you create a report, a blank or empty field is exported as a tab character. If you create a report with the default of a tab as the field separator, then two tab characters in the report file indicate a blank field.
For details on supported Excel versions as part of Microsoft Office, see the system requirements and certification documentation System Requirements and Certification.
Running reports can not only help you maintain data within the system, but also can help identify issues before they become problematic.
You can generate reports for various purposes, as described in the following examples:
To see which dashboards are using an analysis, you can run a Dashboard report including analyses, and search that report for the analysis
To find analyses that are affected by a changed column in a repository table, you can run an Analysis report that includes all columns and formulas, and then search the report for the items that must then be replaced in Catalog Manager.
You can create a report that displays all the dashboard prompts and related fields (such as column, formula, and subject area) within the dashboards. You can also create a report of analyses and extract the filters that are used within those analyses. The following is an example of extracting filters in which the formula is derived using a saved filter that is prompted:
Example: "Markets"."Region" [Filter, prompted]
You can create a report that displays the ACLs for objects. By reviewing the ACLs in the report, you can verify that access to objects is granted to the proper roles with the proper permissions, such as Read/Write. The following line shows an example of ACLs in the report:
"^biconsumer=RX:steve=F", where the caret (^) indicates an application role and "nothing" indicates a user.
Catalog Manager provides the ability to archive and unarchive either an individual catalog folder or an entire catalog.
See the following list for important information on this functionality:
When you archive an individual catalog folder, all objects in the folder and the folder's subfolders are saved in single compressed file. Properties and attributes of objects are included in the archive file.
When you unarchive an individual catalog folder, the archive file is uncompressed and all objects in the folder and the folder's subfolders are then stored in the current offline catalog. Existing folders that have the same names as folders being unarchived are overwritten without warning.
Archiving and unarchiving an entire catalog using Catalog Manager or the Catalog page in Presentation Services is not recommended. Instead, use either the 7-Zip utility or .tar.gz files on UNIX systems for archiving and unarchiving an entire catalog.
When you unarchive with the Preserve ACL option, application roles and users that are part of ACL entries in the archive must exist on the receiving system. Without these application roles and users, the respective ACL entries aren't preserved on the receiving system.
Do not archive an entire catalog by starting at the root level (\). Always specify specific folder names when archiving.
Do not use the following utilities when archiving and unarchiving an entire catalog:
WinZip — The WinZip utility does not always handle extended UNIX file permissions properly. Using the WinZip utility to move catalogs in heterogeneous environments might lead to corrupted catalog files.
FTP — Some third-party FTP programs rename internal files, which might lead to corrupted catalog files. Before moving a catalog using an FTP program, use the 7-Zip utility to compress the catalog into one file.
You can use the Catalog page in Presentation Services to archive and unarchive objects. For information, see Archiving Objects in User's Guide for Oracle Business Intelligence Enterprise Edition.
Use the following procedure to archive a catalog folder.
Timestamps that are assigned to the objects and folders that you are archiving, then select the Keep file time stamps option.
If you do not select this option, then the archiving process does not include timestamp information and the Old option in the Paste Overwrite area of the Preferences dialog is ignored. Upon unarchiving, the system applies a timestamp that indicates the time at which the object or folder is unarchived.
Permissions that are assigned to each object or folder, then select the Keep permissions option.
If you do not select this option, then the archiving process does not include any permissions and the options in the Paste ACL area of the Preferences dialog are ignored. Upon unarchiving, the system assigns the parent folder's permissions to all of the objects and folders.
You can use Catalog Manager to remove a folder from archive.
Unarchiving is similar to pasting and therefore requires that you understand the issues that relate to permissions and ACLS as described in Advanced Options for Pasting Objects. Use the following procedure to unarchive a catalog folder.