16 Configuring and Managing the Oracle BI Presentation Catalog

This chapter describes how to configure and manage the Oracle BI Presentation Catalog and provides information about basic maintenance procedures and configuring for full-text searching.

This chapter includes the following sections:

16.1 About the Oracle BI Presentation Catalog

The Oracle BI Presentation Catalog stores the content that users create in a directory structure of individual files. This content includes folders, shortcuts, Oracle BI EE objects (such as analyses, filters, prompts, and dashboards), and Oracle BI Publisher objects (such as reports and templates).

This section contains the following topics:

16.1.1 Objects in the Catalog

Figure 16-1 shows sample objects in the catalog, as seen in Presentation Services.

Figure 16-1 Sample Objects in the Catalog in Presentation Services

Description of Figure 16-1 follows
Description of ''Figure 16-1 Sample Objects in the Catalog in Presentation Services''

16.1.1.1 Guidelines for Object Names

Each object in the catalog is stored in its own file. For example, an analysis called Analysis 1 is stored in a file named Analysis1. The object name that is visible to users, such as Analysis 1, is referred to as the logical object name.

The following list provides guidelines for object names:

  • No restrictions exist on which characters are allowed in the logical name of an object in the catalog, provided that the characters are valid Unicode characters. The following are valid logical names:

    Hello World
Profit / Loss
% Sales * $ Cost ~~ $ "Expense"?

  • The length of the logical object name must not exceed 256 Unicode characters.

    For more information on Unicode, see Section 16.1.2, "File System Guidelines for Catalogs."

  • The length of the logical path name for an object must not exceed 16000 Unicode characters.

  • The number of directory segments in a logical path name for an object must be not exceed 255 segments.

    For example, a directory with a name such as /n1/n2/n3/n4/…./n253/n254/n255 is acceptable, while a name such as /n1/n2/n3/n4/…./n254/n255/n256 is unacceptable.

  • When you pass the path name of an object using SOAP, you must escape the following characters:

    Forward slash (/)
Backward slash (\)
Tilde (~)
Asterisk (*)
Question mark (?)

    The following logical path names are all valid:

    /shared/test/Hello World
/shared/test/Profit \/ Loss
/shared/test/% Sales \* $ Cost \~\~ $ "Expense"\?

    Use care when building a catalog path. It is very common to see code that assumes the forward slash (/) is always a path separator. Always verify your path code with an object name such as "Profit / Loss".

  • When you pass a catalog search filter using SOAP, you must escape the following characters:

    Forward slash (/)
Backward slash (\)
Tilde (~)
Asterisk (*)
Question mark (?)
Caret (^)
Dollar sign (?)

    The following search filters are all valid:

    Hello World
Profit \/ Loss
% Sales \* \$ Cost \~\~ \$ "Expense"\?

16.1.1.2 Attribute Files for Objects

Each object has a corresponding attribute file. For example, the analysis called Analysis1 would have a corresponding attribute file named Analysis1.atr. The attribute file contains the object's full name, access control list (ACL), description, and so on. To access an object in the catalog, users must have appropriate ACL entries for that object. All objects in the catalog use ACL entries.

16.1.1.3 Lock Files for Objects

To guarantee that only one user can write to a file at one time, a lock file is created when an object is being written to. On rare occasions (for example, after a power outage), temporary lock files in the catalog might not be removed completely. If Presentation Services reports of such a lock file, then you must delete it manually.

16.1.2 File System Guidelines for Catalogs

This section describes the following guidelines for working with objects in catalogs in file systems:

16.1.2.1 Handling Users of the Catalog

The catalog is designed to scale to thousands of concurrent users. To achieve this scaling, the catalog adheres to the following guidelines:

  • The average user typically only reads from the catalog and rarely, if ever, writes to it. Each user is constantly and automatically updating his or her Most Recently Used file, but each user's "read" operations still far outweigh the user's "writes" operations. Therefore, the read-to-write ratio is typically at least 100 to 1.

  • While a locking mechanism guarantees that only one user can write to an object at a time, it is rare for multiple users to attempt to write simultaneously to the same object. A feature called "lazy locking" enables users to continue reading an object even when another user is updating that object.

  • Modern file systems cache "small" files directly inside the directory record, such that reading any information on a directory simultaneously loads all small files directly into the operating system's memory cache. Therefore, it is good practice to keep files in the catalog "small," especially the frequently "read" .atr metadata files. When these metadata files remain small, then all the .atr files in a directory are loaded into memory with one physical hard disk read. Every file that exceeds the "small" threshold adds another physical hard disk read, which can cause a 100% degradation for each large file. In other words, use care when considering storing arbitrary "Properties" in .atr files.

  • Reading an object's .atr metadata file using NFS is far slower than reading it directly from a local disk. For this reason, Presentation Services additionally caches all .atr files internally. This cache can become briefly "stale" when another node in the cluster writes data to the file that is newer than the data that is cached by the current node. Therefore, all nodes are refreshed according to the MaxAgeMinutes element in the instanceconfig.xml, whose default for a cluster is 5 minutes. This default setting commonly achieves the best trade-off between the possibility of stale data and the known performance impact. (The default for an environment without clusters is 60 minutes.)

    You can modify the MaxAgeMinutes element for your system. Its parent elements are Cache and CatalogAttributes.

16.1.2.2 Handling Heterogeneous Nodes

To allow heterogeneous nodes in a cluster, the catalog adheres to the following guidelines:

  • The maximum length for the name of an object on disk is 256 bytes, which is 64 Unicode characters. The logical name is restricted to 256 Unicode characters. To adhere to this restriction, logical names greater than 32 characters are hashed.

  • The maximum length for the name of a path on disk is 32KB, which is 8000 Unicode characters. The logical path is restricted to 16000 Unicode characters.

  • All path names on disk are all lowercase. The logical path name allows mixed case, but is still case-insensitive.

  • Certain characters are not allowed for path names on disk, while the logical path name allows all characters. For example, Windows systems disallow certain characters such as the colon (:), so those characters are mapped using standard HTML escape sequences. For example, the period character (.) becomes "%2e".

  • Certain file names are not allowed on disk, while the logical object name has no restrictions. For example, Windows systems disallow certain file names such as COM, so those names are mapped using standard HTML escape sequences. For example, "com" becomes "co%6d".

16.1.2.3 Handling Catalog Files on Various Platforms

Keep the following points in mind when handling catalog files on various platforms:

  • For UNIX Platforms: UNIX kernels must commonly be configured to allow more than 4000 subdirectories per directory. See Section 16.2.1, "Manually Changing Configuration Settings for the Catalog" for information on the HashUserHomeDirectories element.

  • For Windows Platforms:

    When users want to navigate catalog files using a tool such as Microsoft Windows Explorer, then they want the catalog structure based on a short path name such as c:/obi/demo, rather than the long default path name. Note that such navigation is not recommended.

    • FAT is not supported, and NTFS is required.

    • Performance on Windows platforms degrades noticeably when more than 8000 files exist in a single directory. Because each catalog object has two files (the data file and the .atr metadata file), it is strongly recommended that you not store more than 4000 catalog objects in a single directory. See Section 16.2.1, "Manually Changing Configuration Settings for the Catalog" for information on the HashUserHomeDirectories element.

    • Windows Explorer does not handle long path names properly, and it is recommended to not use Windows Explorer to navigate the internal structure of the catalog. While the file system can handle path names as large as 32KB and Presentation Services is not negatively affected, you cannot use Windows Explorer with any path name that is longer than approximately 2KB.

      Because a single Unicode character can require as many as 4 bytes, you might be unable to use Windows Explorer with path names of only 500 Unicode characters. This limitation does not affect Presentation Services. Because of this limitation, place the catalog in a top-level directory, such as c:\mycatalog\sales.

16.1.2.4 Known Issues with Catalog Files

The following issues are known when working with catalog files:

  • Locking across NFS systems is difficult, but Presentation Services provides an effective locking mechanism in recent versions. Obtain key patches to update older versions of Oracle BI EE as necessary.

    For more information, see Section 16.2.4, "Validating the Catalog."

  • Various third-party FTP programs have issues handling '%' escape sequences, which often results in a renamed file that is doubly escaped. For example, a file that is named sa%2epaint (whose logical name is SA.Paint) is incorrectly renamed to sa%252epaint (whose logical name is SA%2ePaint).

    Avoid using an FTP program directly against a catalog. Instead, download and use the 7-Zip utility to compress the catalog files, then use an FTP program to transfer the resulting compressed file.

16.2 Maintaining the Oracle BI Presentation Catalog

This section contains the following topics on maintaining a catalog:

16.2.1 Manually Changing Configuration Settings for the Catalog

You modify settings manually using various elements in the instanceconfig.xml file to change these settings.

To manually change configuration settings for the catalog:

  1. Open the instanceconfig.xml file for editing located in:

    BI_DOMAIN/config/fmwconfig/biconfig/OBIPS

    as described in Section A.1, "Configuration Files".

  2. Locate the Catalog section in which you must add the following element:

    • HashUserHomeDirectories: Specifies the hashing of directories. If you have more than 4000 catalog users or if you intend to have more than 4000 catalog users in the future, then you must turn on the hashing of users' home directories to address a file system limitation. To do so, set the HashUserHomeDirectories element to 2 from its default value of 0. When this element is turned on, for example, the default name for user Steve's home directory would become /users/st/steve.

    Caution:

    Keep the following points in mind:

    • Hashing is not typically needed for modern operating systems that use modern file systems (for example, ext4, ZFS, ntfs); however, it may still be useful for performance when your user base exceeds approximately 4,000 users.

    • Oracle recommends that you hash a catalog at creation time; however, there are circumstance that require hashing the catalog after it is in use. Take a backup and run the following command for more information:

      On UNIX:

      runcat.sh -cmd rehash -help

      On Windows:

      runcat.cmd -cmd rehash -help

    • In general, do not set the HashUserHomeDirectories element to a value greater than 2, because a higher setting negates the effectiveness of hashing.

    • Include only one Catalog element in the instanceconfig.xml file or unexpected results might occur. Unless expressly noted, include most nodes in an XML document only once.

  3. Include the element and its ancestor element as appropriate, as shown in the following example:

    <ServerInstance>
<Catalog>
    <HashUserHomeDirectories>2</HashUserHomeDirectories>
</Catalog>
</ServerInstance>

  4. Save your changes and close the file.

  5. Restart Presentation Services.

16.2.2 Deploying Catalogs and Objects to Production

You can deploy catalogs and simple objects (for example, a dashboard with privileges) to a production environment from a test environment, as described in the following sections:

16.2.2.1 Deploying Catalogs to Production

In a Windows environment, you must use the 7-Zip utility. Do not use any other compression utility. In a UNIX environment, you can use the tape archiving (or tar) command and a compression utility, such as GZzip, to archive an entire catalog in a test environment. Then, you can use 7-Zip or tar to unarchive the file in the production environment.

Caution:

Do not use Catalog Manager for archiving and unarchiving entire catalogs.

Do not use an FTP program directly against a catalog.

16.2.2.2 Deploying Objects to Production

You can deploy objects (for example, a dashboard with privileges) to a production environment from a test environment.

To deploy catalog objects to a production environment:

  1. (Optional) If you are deploying a catalog object to a new production environment.

    Archive the catalog object in the test environment and unarchive it in the production environment as follows:

    1. Archive the catalog object in the test environment using one of the following:

    2. Copy the archived file to the production computer.

    3. On the production computer, unarchive the object.

      For information about how to unarchive an object, see Section 16.10, "Archiving and Unarchiving Using Catalog Manager."

    4. Set the permissions on the object as appropriate.

  2. (Optional) If you are deploying the catalog to an existing production environment.

    Copy and paste new or updated objects from the test catalog into the production catalog as follows:

    1. Open two Catalog Manager windows: one with the test catalog, and another with the production catalog.

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

16.2.3 Updating Catalog Objects

If you upgrade to a newer version of Oracle Business Intelligence or install a patch and work with objects in the catalog, then you might notice that certain objects are not being accessed as quickly as in the previous release. This change can occur if objects were not upgraded properly. You can confirm the need to update by viewing the metrics in Fusion Middleware Control. In the Catalog folder, find a metric called "Reads Needing Upgrade" with description "The number of objects read that required upgrading." If the number is large, then you can resolve this issue by updating objects in the catalog using the Administration page in Presentation Services.

You can upgrade to new versions of Oracle Business Intelligence by following the instructions in Oracle Fusion Middleware Upgrade Guide for Oracle Business Intelligence. The "Task 5: Upgrade the Oracle BI Repository and Catalog" section of that guide contains complete information for upgrading catalog objects and describes the recommended upgrade approach, which is to upgrade thoroughly when Presentation Services is not running. If you suspect that the upgrading of objects was not performed thoroughly during the upgrade process, then you can update the objects yourself using the Administration page. The advantage of this approach is that Presentation Services can stay up and running during the update.

Bear the following points in mind as you prepare to update objects:

  • If you are performing a rolling upgrade of machines in a cluster, then do not use this option or the UpgradeAndExit configuration setting until all machines in the cluster are upgraded.

  • Use this option on only one node in a cluster at a time.

To update catalog objects:

  1. In the global header, click Administration.

  2. Click the Scan and Update Catalog Objects That Require Updates link.

  3. Click Update Catalog Objects to begin the update process.

    Click the other links on the page to see which objects were updated and which were not. You can view the log files for details on objects that were not updated.

16.2.4 Validating the Catalog

Over time, inconsistencies can develop in the catalog as links are broken, users are deleted, or NFS file system issues are encountered. These inconsistencies can eventually lead to incorrect behavior, such as the inability to edit an agent's recipient list. You can periodically take the production system offline and validate the catalog, to be informed of and to take corrective action on inconsistencies.

This section contains the following topics about validating the catalog:

16.2.4.1 Process: Validating the Catalog

The process of validating the catalog involves creating a report for the catalog in offline mode and seeing the objects that require adjustment or removal. You might fix some objects manually in offline mode. Then run the validate operation again to allow the system to "clean" by deleting any unnecessary objects. You repeat the process of creating the report, manually fixing errors, and cleaning the catalog until it is validated.

16.2.4.2 Tasks in the Validation Process

The validation process performs the following tasks:

  • Ensures that each object in the catalog is larger than zero bytes.

  • Ensures that each item in the catalog has a valid corresponding .atr file.

  • Ensures that each link in the catalog is valid.

  • Ensures that the files in the account cache are valid.

  • Ensures that all XML objects in the catalog pass schema validation.

  • Attempts to repair object names that were damaged by ftp programs.

16.2.4.3 Important Guidelines for Validating the Catalog

Before you validate the catalog, keep the following guidelines in mind:

  • Use care when validating a catalog in a development environment, if that environment has a different security store from the production environment. If the validation is performed with a different security store, then many accounts might be removed from the catalog.

  • When you turn on any validation of the catalog, all ACLs (that is, all privileges and every item's permissions) are "scrubbed," which means that dead accounts are removed from them and any changed items are written to disk. Therefore, even if you simply create a report without fixing any broken items automatically, you might find that the catalog is still extensively "changed."

  • Before validating the catalog in a clustered environment, do one of the following:

    • Shut down the Presentation Services cluster and run the validation directly against the cluster's catalog.

    • Make a copy of the cluster's catalog and run the validation against that copy.

      Before using the 7-Zip utility to make a copy of a catalog, first shut down all nodes in the Presentation Services cluster or put all nodes in that cluster into Maintenance Mode (which is the recommended approach).

      Be aware that any changes that are made to the catalog online concurrently to the validation process are not included in the validation.

      While backing up the catalog is always good practice, there is no practical difference between running validate against the catalog directly versus running the validation on a backup copy.

16.2.4.4 Performing a Basic Validation of the Catalog

You can perform a basic validation of the catalog on an ad-hoc basis as needed, immediately before pushing content from a development environment to a production environment, or per a regular schedule, such as on the first Tuesday of every month.

To validate the catalog:

  1. Stop Presentation Services.

    For information, see Section 2.4, "Using Fusion Middleware Control to Start and Stop BI System Component Processes."

  2. Back up the catalog by using the 7-Zip utility to create a compressed file for it.

  3. Create a backup copy of the instanceconfig.xml file located in:

    BI_DOMAIN/config/fmwconfig/biconfig/OBIPS

  4. Edit the instanceconfig.xml file so that it contains the appropriate elements for performing the validation. You must set the elements to perform the tasks for creating the report and "cleaning" the catalog at the appropriate times.

    For information on these elements, see Section 16.2.4.5, "Specifying the Elements for Validating the Catalog."

  5. Start Presentation Services to run the validation according to the values that you specified in the instanceconfig.xml file.

  6. Edit the instanceconfig.xml file again so that it contains the appropriate elements for performing the validation. You must set the elements to perform the tasks for creating the report and "cleaning" the catalog at the appropriate times.

  7. Repeat Steps 5 through 7 until the catalog is validated.

  8. Stop Presentation Services.

  9. Create a backup copy of the instanceconfig.xml file in which you added the validation elements, renaming the file similar to instanceconfig_validate.xml. In this way, you have a version of the file to use as a starting point for subsequent validations.

  10. Restore the backup version of the instanceconfig.xml that you created earlier to use as the current version.

  11. Start Presentation Services.

16.2.4.5 Specifying the Elements for Validating the Catalog

As part of the process of validating the catalog, you include elements in the instanceconfig.xml file that run the validation when you restart Presentation Services. The following procedure describes how to edit the instanceconfig.xml file to include these elements.

To specify the element for validating the catalog:

  1. Open the instanceconfig.xml file for editing, located in:

    BI_DOMAIN/config/fmwconfig/biconfig/OBIPS

  2. Locate the Catalog section in which you must add the elements that are described in Table 16-1.

  3. Include the elements and their ancestor element as appropriate, as shown in the following example. In this example, the validation runs when Presentation Services starts, and Presentation Services is stopped when the validation is complete. Inconsistent accounts (such as those for deleted users), links, and objects are removed. Inconsistent users' home directory names are logged but directories are not removed.

    <ServerInstance>
<Catalog>
    <Validate>OnStartupAndExit</Validate>
    <ValidateAccounts>Clean</ValidateAccounts>
    <ValidateHomes>Report</ValidateHomes>
    <ValidateItems>Clean</ValidateItems>
    <ValidateLinks>Clean</ValidateLinks>
</Catalog>
</ServerInstance>

    Caution:

    Include only one Catalog element in the instanceconfig.xml file or unexpected results might occur. Unless expressly noted, include most nodes (such as that for the Catalog element) in an XML document only once.

  4. Save your changes and close the file.

Table 16-1 Elements for Validating the Catalog

Element Description Default Value

Validate

Performs the validation of the catalog according to the values of the other Validate-related elements in this section. Values are described in the following list:

  • None — Performs no validation.

  • OnStartupAndExit — When Presentation Services starts, performs the validation, performs the Report or Clean operation, then stops Presentation Services. You run through multiple cycles of Report, Clean, Report, and so on for each element (such as ValidateAccounts, ValidateHomes, ValidateItems, and ValidateLinks) until the catalog is validated.

If this value is not None, then all privileges and each object's ACLs in the entire catalog are cleaned of terminated accounts, regardless of the settings of the other Validate-related elements.

None

ValidateAccounts

Verifies that all information about users, roles, and groups in the catalog is consistent. Values are described in the list after this table.

None

ValidateHomes

Verifies that all information about home directories in the catalog is consistent. Values are described in the list after this table.

ValidateHomes is executed only if ValidateAccounts is set to either Report or Clean.

None

ValidateItems

Verifies that all information about objects in the catalog is consistent. Values are described in the list after this table.

None

ValidateLinks

Cleans shortcuts in the catalog, but does not reconcile internal references to objects. For example, suppose that a dashboard page includes the text: "display the results here after running /shared/sales/myfavreport". If a user subsequently deletes the myfavreport object, then no fix or message is indicated during validation. Values are described in the list after this table.

None

The elements have the values that are described in the following list:

16.3 About Catalog Manager

Catalog Manager is a tool that lets you perform online and offline management of Oracle BI Presentation Catalogs. Install Catalog Manager on a secure computer that is accessible only to Oracle BI Administrators.

16.3.1 Uses for Catalog Manager

You can use Catalog Manager to:

  • Manage folders, shortcuts, global variables, and objects (analyses, filters, prompts, dashboards, and so on). For example, you can rename and delete objects, and you can move and copy objects within and between catalogs.

  • View and edit catalog objects in Extensible Markup Language (XML).

  • Preview objects, such as analyses and prompts.

  • Search for and replace catalog text.

  • Search for catalog objects.

  • Create analyses to display catalog data.

  • Localize captions. See Section 14.2.2, "Localizing Oracle BI Presentation Catalog Captions."

Many of the operations that you can perform in Catalog Manager can also be performed through the Catalog page in Oracle BI Presentation Services. For information, see "Managing Objects in the Oracle BI Presentation Catalog" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

16.3.2 Guidelines for Working with Catalog Manager

Follow these guidelines when working with Catalog Manager:

  • Always make backup copies of the Oracle BI Presentation Catalogs that you are working with.

  • Be sure of changes that you plan to make. Catalog Manager commits changes immediately. There is no undo function nor are there any error messages to tell you that a particular change does not display well to users. However, if you do make any unwanted changes, then you can revert to your latest saved backup.

  • Do not copy and paste catalog contents into email, as this is not supported.

16.3.3 Tips for Working with Catalog Manager

As you work with Catalog Manager, keep the following tips in mind:

  • While working in online mode, you can paste catalog contents into or out of a read-only folder by turning off the read-only property of the folder tree before copying, then re-apply the read-only attribute after pasting.

  • You cannot copy, archive, or drag files from the /system/security directory in the Catalog Manager.

  • Some keyboard shortcuts might not work properly.

  • Even if a resize indicator is not shown, Catalog Manager panes might still be resizable.

  • You can use Catalog Manager in languages other than English. For information, see Section 14.3, "Setting the Current Locale in Catalog Manager."

16.4 Starting Catalog Manager and Opening Catalogs

This section describes the following topics:

16.4.1 Requirements for Running Catalog Manager

The following list describes the requirements for running Catalog Manager:

  • Graphical User Interface — You can invoke the user interface on the following platforms:

    • Windows 64-bit

    • Linux 64-bit

  • Command Line Utility — You can invoke the command line utility on supported platforms for Oracle Business Intelligence such as Windows, Linux, IBM-AIX, Sun Solaris, and HP-UX. Enter a command such as the following one on Linux for assistance in using the command line utility:

    ./runcat.sh -help

16.4.2 Starting the Catalog Manager User Interface

You can start the user interface for Catalog Manager using menu options on Windows or a command on Windows or Linux.

To start the graphical user interface for the Catalog Manager:

  1. On Windows, from the Start menu, select Oracle Business Intelligence, then Catalog Manager.

    or

    Using the command line, change to the following directory:

    BI_DOMAIN\bitools\bin

    then run the appropriate script:

    runcat.cmd (on Windows)

    runcat.sh (on Linux)

Figure 16-2 shows sample objects in the Catalog Manager for Windows platforms.

Figure 16-2 Sample Objects in Catalog Manager for Windows

Description of Figure 16-2 follows
Description of ''Figure 16-2 Sample Objects in Catalog Manager for Windows''

16.4.3 Resolving Startup Issues on Linux Systems

You must start the Catalog Manager in a graphical user interface xterm on Linux systems. Examples of xterms are a native gnome, kde console, VNC, or a local x-server such as Xming, Tarantella, Hummingbird Exceed, or Citrix. (These examples do not constitute a statement of certification or support.) You cannot start the graphical user interface for Catalog Manager using an ASCII text terminal, such as PuTTy or FSecure or a command-line SSH.

If the Catalog Manager does not start, then verify the following:

  • That you can run a native application such as xclock or xeyes.

  • That you can start Catalog Manager with a native console or with VNC. Sometimes operating system administrators can lock X-Windows.

  • That you can run the following command, which allows all xterm connections:

    xhost +

  • That you can run Catalog Manager from the command line with debugging enabled to see if any additional output is produced, using the following command:

    ./runcat.sh -consoleLog -noExit

  • That you can use an operating system utility such as strace to trace the execution of the runcat.sh command and see if any error messages are generated, such as those relating to libraries or files being unable to open. You can use the Eclipse Java plug-in that requires the standard widget toolkit (SWT), which in turn requires GTK (Gimp Toolkit) to be installed. Enter the following command:

    strace -aef -o ./runcat_trace.txt runcat.sh

16.4.4 Understanding the Two Catalog Modes

You can open a catalog in one of two modes — online or offline. Both modes can operate against an actual production catalog, with no need for any downtime.

16.4.4.1 Online Mode

In online mode, you connect to a catalog on a running web server. In this mode your permissions are applied, you can select a locale, and you can see the effects of any localization on the catalog. You can see only those objects for which you have the appropriate permissions. Both Presentation Services and the web server must be running for you to open catalogs in online mode.

Use online mode when you want to make minor incremental changes or additions to the catalog, such as changes to permissions, updates to a single object, or migration of new objects to a production environment.

16.4.4.2 Offline Mode

In offline mode, you connect to a local file system. In this mode, you are logged in as a super user or system user, and no permissions are applied. You can see all objects in the catalog.

Generally, working in offline mode is faster than working in online mode. This is because you are accessing, creating, and updating the individual files directly, and the catalog does not have to communicate with Presentation Services as it does when you are working in online mode.

Use offline mode when you want to make catalog-wide changes, such as globally renaming objects or moving multiple objects for reorganization, as described in the following procedure.

To make systemwide changes to the catalog:

  1. Place Presentation Services in Maintenance Mode.

    In a clustered environment, you can place any instance of Presentation Services in Maintenance Mode and within a few minutes, all other instances in the cluster automatically go into Maintenance Mode too. In a clustered environment only, wait a few minutes before performing the tasks for which you placed Presentation Services into Maintenance Mode.

    For information on Maintenance Mode, see "Administration page" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

  2. Back up the catalog by using the 7-Zip utility to create a compressed file for it.

  3. In Catalog Manager, open the catalog in offline mode, as described in Section 16.4.6, "Opening an Oracle BI Presentation Catalog."

  4. Make the systemwide change.

  5. Back up the catalog again.

  6. Take Presentation Services out of Maintenance Mode.

    In a clustered environment, you can take any instance of Presentation Services out of Maintenance Mode and within a few minutes, all other instances in the cluster automatically go out of Maintenance Mode too. So in a clustered environment only, a few minutes are required before users can resume editing catalog content.

16.4.5 Operations Available in Online Mode and Offline Mode

Many of the operations that you can perform using Catalog Manager are available in both online mode and offline mode. A few operations are available in only one mode or the other. Generally, the operations available in:

  • Online mode are read-only operations and write operations that do not affect the entire catalog, such as setting permissions for an object.

  • Offline mode include most of the operations available in online mode and write functions that affect the entire catalog.

You can perform the following operations in online and offline modes (or as stated), as follows:

  • Cutting objects.

  • Copying objects.

  • Pasting objects.

  • Copying objects for another catalog.

  • Pasting objects from another catalog.

  • Creating shortcuts of objects.

  • Deleting objects.

  • Renaming objects without reference updates.

  • Renaming objects with reference updates. (This feature is known as Smart Rename and is available in both modes. In offline mode, you can rename all objects. In online mode, you might be unable to rename certain objects, depending on your permissions.)

  • Refreshing the Catalog Manager workspace.

  • Creating folders.

  • Setting permissions for objects.

  • Working with properties of objects.

  • Managing the view of the workspace.

  • Searching for objects.

  • Searching for and replacing catalog text. (This feature is available in both modes. In offline mode, you can replace all objects. In online mode, you might be unable to replace certain objects, depending on your permissions.)

  • Creating reports to display Catalog Manager data.

  • Setting browser preference.

  • Previewing objects (available in online mode only).

  • Exporting captions for localization purposes.

16.4.6 Opening an Oracle BI Presentation Catalog

To open an Oracle BI Presentation Catalog:

  1. In Catalog Manager, from the File menu, select Open Catalog.

  2. Complete the necessary fields, as described in the following list:

    • Type — Select the mode (online or offline) in which to open the catalog

    • Path — If you are opening the catalog in offline mode, then enter the path to the catalog folder on the local file system, for example:

      Click Browse to display a dialog for locating the catalog.

      SDD/metadata/content

      Where SDD is the Singleton Data Directory for example, DOMAIN_HOME/bidata (for more information, see Section 1.4, "Key Directories in Oracle Business Intelligence").

    • URL — If you are opening the catalog in online mode, then enter the URL to Oracle BI Presentation Services, for example:

      https://hostname/analytics/saw.dll

    • User — If you are opening the catalog in online mode, then enter the user name for the host URL (disabled in offline mode).

    • Password — If you are opening the catalog in online mode, then enter the password for the host URL (disabled in offline mode).

    • Locale — Select the locale to use for user interface elements in Catalog Manager and for objects in the catalog, when opening the catalog in online mode.

    • Read-Only — Select this field to open the catalog in read-only mode (disabled in offline mode).

  3. Click OK.

When specifying the URL for the catalog in online mode, ensure that you specify https rather than http, for increased security. If you specify http, then you see a message box after closing the Open Catalog dialog that prompts you to verify the opening of the catalog using an unsecured connection. To use https when opening catalogs, you must configure Oracle BI EE for Secure Socket Layer communication, as described in "SSL Configuration in Oracle Business Intelligence" in Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition.

16.5 Using the Catalog Manager Workspace

This section provides the following topics on the workspace for Catalog Manager:

16.5.1 What Does the Catalog Manager Workspace Do?

The Catalog Manager workspace enables you to view and work with catalog objects. It displays the following folders for an open catalog:

  • The shared folder— Contains content that is shared among catalog users. This includes the preconfigured dashboards and analyses that are distributed with prebuilt applications, and other objects such as shared filters.

  • The system folder — Contains administrative elements of Presentation Services. Some of these elements are distributed with the product, and others are configured by you as the administrator, such as privileges. Avoid modifying any files in this folder. Presentation Services uses these files internally and modifying them might cause unexpected results.

  • The users folder — Contains content that catalog users with the appropriate permissions have saved to their personal folders, such as individual analyses.

16.5.2 What Does the Catalog Manager Workspace Look Like?

Catalog Manager consists of the following main components:

  • Menu bar — Lets you access the following menus:

    • File — Provides options that let you open and close catalogs, exit Catalog Manager, and so on.

    • Edit — Provides options that let you manage catalog objects, such as Cut, Copy, Permissions, and so on. (Many of these options are also available on the right-mouse menu.)

    • View — Provides options to manage the view of the Catalog Manager workspace, such as Show Tree, Show Job Status, and so on.

    • Tools — Provides options that let you manage catalogs, such as XML Search and Replace, Create Report, and so on.

    • Help — Provides options to access the Oracle BI Enterprise Edition website and to display information about Catalog Manager.

  • Toolbar — Provides quick access to commonly used options, such as Cut, Copy, Paste, and so on.

  • Tree pane — Displays catalog folders. The pane also displays objects but only if the Show Objects in Tree option on the View menu is selected.

  • Table pane — Displays catalog folders and objects. It consists of:

    • The navigation bar, where you can move to the catalog object to work with by typing its path name.

    • These columns: Name, Type, Owner, My Permissions, Attributes, Date Created, and Last Modified. Click the column name to sort by that value, such as by type.

      The Type column identifies the type of object. Objects that are identified as "unknown file" are generally internally used objects, and their type is not exposed in Catalog Manager.

  • Right-mouse menu — Provides options that let you manage catalog objects, such as Rename, Properties, Permissions, and so on. (Many of these options are also available on the Edit menu.)

16.5.3 Managing the View of the Catalog Manager Workspace

You can manage what you view in the Catalog Manager. For example, you can show objects in the Tree pane or show job statuses.

To manage the view of the Catalog Manager workspace:

  1. In Catalog Manager, select View and then one of these options:

    • Show Tree — Displays the Tree pane, if you previously had closed it.

    • Show Table — Displays the Table pane, if you previously had closed it.

    • Show Job Status — Displays the Background Job Status pane, where you can view the progress of processes that you have run, such as Search and Replace, Smart Rename, and so on. You can also remove all finished jobs and set progress preferences using the icons in the upper-right corner of the pane.

    • Show Objects in Tree — Displays objects (that is, analyses, filters, and so on) in addition to folders in the Tree pane.

    • Refresh — Refreshes the objects that are displayed in the Tree and Table panes. (You might want to refresh the data, for example, if someone else makes changes to the catalog while you are working with it and you want to see the changes.)

16.6 Working with Objects in Catalog Manager

This section provides the following information about working with objects:

In the Catalog page of Presentation Services, you can view folders and contents including hidden objects. You can create, rename, copy, move, and delete folders and contents. For more information, see "Managing Objects in the Oracle BI Presentation Catalog" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

Note:

Changes made in the Presentation layer of the Oracle BI Administration Tool can affect analyses and dashboards based on those tables and columns. You can use Catalog Manager to keep the catalog synchronized with these changes in the Presentation layer.

16.6.1 Searching for Catalog Objects Using Catalog Manager

You can search for objects in the catalog using the Search function. For example, you might want to search for all objects that have a property with the value of "administrator."

When you search, you can limit the search by:

  • Case Sensitive — Select this check box to apply case sensitivity to the search criteria. The default value is unchecked.

  • Name — Limits the search to the names of objects.

  • Description — Limits the search to the Description property.

  • Property values — Limits the search to the values of properties.

  • Owner — Limits the search to the owners of objects.

  • XML — Limits the search to XML.

  • Object type — Searches for all types of objects or limits the search to a specific type of object that you specify (for example, analyses, filters, agents, dashboard prompts, dashboard pages).

  • Date — Limits the search to objects that were created on the dates that you specify or to objects that were last modified on the dates that you specify.

To search for an object:

  1. In Catalog Manager, open the catalog and navigate to the location in the tree where you want to begin the search.

  2. Click Search on the toolbar.

  3. In the Search for any or all criteria below field, enter the word or phrase to search for.

  4. To make the search case-sensitive, select the Case Sensitive box.

  5. To limit the search, then click Advanced Search.

  6. In the Advanced Search area, specify the constraints for the search.

  7. Click Search.

    Tip:

    When you have finished searching, click Explore the entire catalog tree on the toolbar to return to the Tree and Table panes.

16.6.2 Copying and Pasting Objects

You can copy and paste objects within a single catalog. You can also copy objects from one catalog and paste them into another catalog.

16.6.2.1 Tips for Copying and Pasting

Use the following tips as you copy and paste objects:

  • You can copy and paste objects using the following methods:

  • Catalogs are structured in hierarchical folders. When copying or merging objects, remember to also copy any objects that are associated with them, such as dashboard folders, shortcuts, and analyses. URL paths in external applications can be reestablished after a copy or merge operation if the entire folder path is not copied, for example, if added to the dashboard as a shortcut or text.

  • Most often, you can simply copy and paste objects as needed. If required, you can set advanced options that affect the objects that you are pasting. For complete information, see Section 16.6.2.2, "Advanced Options for Pasting Objects."

16.6.2.1.1 Copying and Pasting Objects Between Catalogs Using Menus

The following procedure describes how to copy and paste objects between two catalogs using menu options. If the two catalogs have the same name, then you might want to rename one of the catalogs before opening it to help distinguish between the two catalogs as you work. Both catalogs must be the same version 11.1.1 (or later).

To copy and paste objects between catalogs using menus:

  1. In Catalog Manager, open the catalog to change, that is the target catalog.

  2. Using another instance of the Catalog Manager, open the catalog that contains the objects to copy, that is the source catalog.

  3. If necessary, reposition both instances of Catalog Manager on your screen so you can display the title bars of both Catalog Manager instances.

  4. In the Catalog Manager instance that shows the source catalog, right-click the source object and select Copy.

  5. In the Catalog Manager instance that shows the target catalog, right-click at the point where you want to paste the source object and select Paste.

16.6.2.2 Advanced Options for Pasting Objects

You can set advanced options in the Preferences dialog for pasting objects that you have copied, as described in the following sections:

Important:

You must set the advanced options in the Preferences dialog before you begin the copy and paste operation, for them to take effect.
16.6.2.2.1 Paste Overwrite

The Preferences dialog contains the following options in the Paste Overwrite area:

  • Force — Pastes all files, overwriting even those that have the read-only attribute set.

  • All — Pastes all possible files, overwriting only those that do not have the read-only attribute set. (Default)

  • Old — Pastes all possible files, but does not overwrite any existing files unless they are older than the source.

  • None — Pastes all possible files, but does not overwrite any existing files.

Consider the following example of pasting with overwrite options set. Suppose that the /users/joe folder contains the following analyses:


Analysis A (created 01-Jan-2010)
Analysis B (created 31-May-2010)
Analysis C (created 01-Jan-2010)

Suppose that the /users/sue folder contains the following analyses, but no Analysis C


Analysis A (created 28-Feb-2010)
Analysis B (created 01-Jan-2010)

Suppose that Sue copies the A, B, and C Analyses from the /users/joe folder and pastes them to the /users/sue folder. If the Paste Overwrite option is set to:

  • None, then Sue keeps her A and B Analyses, and Joe's analyses are ignored. Sue gets a copy of Analysis C.

  • All, then Sue's A and B Analyses are overwritten with Joe's, and Sue gets a copy of Analysis C.

  • Old, then Sue keeps her A Analysis (Sue's A Analyses is not "old"), Sue's B Analysis gets overwritten by Joe's analysis (Sue's B Analysis was "old"), and Sue gets a copy of Analysis C.

16.6.2.2.2 Paste ACL

The Preferences dialog contains the following options in the Paste ACL area:

  • Inherit — Inherits the object's permissions (ACL) from its new parent folder. (Default)

  • Preserve — Preserves the object's permissions (ACL) as it was in the original, mapping accounts as necessary.

  • Preserve Only Groups — Same as Preserve, but applies to group accounts and Application Roles, not to user accounts. This is for a development to production environment in which a customer might use the same groups (such as Sales and Marketing) in both development and production. However, the users in each group might be very different, such as TestUserA and TestAdminB in development and Steve and Sue in production.

  • Create — Preserves the object's permissions (ACL) as it was in the original, creating and mapping accounts as necessary, depending on the mode and type of owner, as described in the following list:

    • Online mode — In online mode, Catalog Manager is communicating with the back-end security server. Catalog Manager knows about the users and application roles from that server and can usually paste a copied object with the appropriate user name or role. While pasting objects, keep in mind that you might lack appropriate permissions to create accounts for certain objects.

    • Offline mode — In offline mode, Catalog Manager has no connection with the back-end security server, so it is unaware of users and application roles that are stored there, unless their names are available in the cache for the catalog. If the name of the user or role for a copied object is not available in the cache, then Catalog Manager cannot paste the copied object with that name or role. Instead, the pasted object inherits its owner from its new parent folder, which is similar to the Inherit option.

      However, because Catalog groups are stored in the catalog rather than in the back-end security server, then Catalog Manager can associate Catalog groups with pasted objects as appropriate.

    This feature is used in applications whose administrators create accounts in a staging area before moving the users to the production environment.

  • Create Only Groups — Same as Create, but applies only to Catalog groups, not to user accounts. Works in a development to production environment similarly to Preserve Only Groups.

If you have the appropriate permissions, then you can select a newly pasted object and set ownership recursively to the appropriate user.

Consider the following example of pasting with ACL options set. Suppose that Steve owns the /users/steve/MyFavReport folder and has permissions (ACL) "all users can read/execute, steve has full control". Joe (who has some administration privileges) logs in and copies MyFavReport, pasting it to /users/sue (which is owned by "administrator", with permissions "admins have full control, sue has full control").

If Joe sets the Paste ACL option to:

  • Inherit, then the /users/sue/MyFavReport folder is owned by Joe with whatever permissions are set on the /users/sue folder (that is, "admins have full control, sue has full control").

  • Preserve, then the /users/sue/MyFavReport folder is owned by Joe with whatever permissions were set on the /users/steve/MyFavReport folder (that is, "all users can read/execute, steve has full control"). If Joe pastes in a second Catalog Manager and if "steve" does not exist in this Catalog, then the permissions for Steve are discarded. If "steve" exists but has a different user ID, then Steve's user ID is mapped to the new one.

  • Create in online mode, then the /users/sue/MyFavReport folder is owned by Joe with whatever permissions were set on the /users/steve/MyFavReport folder (that is, "all users can read/execute, Steve has full control"). If Joe pastes in a second Catalog Manager and if "steve" does not exist in this catalog, then the owner is inherited from the parent folder. (The Create option is deprecated in Release 11g as it applies only to Catalog groups.)

16.6.3 Renaming Catalog Objects

You can rename objects in the catalog. This can be useful when you are migrating from a test environment to a production environment.

There are two ways to rename an object:

  • Rename without reference updates — Renames the object and preserves the references to the original name that other catalog objects might have.

  • Rename with reference updates — Renames the object and changes references that other objects might have to the new name (that is, original name references are not preserved). This feature is also known as Smart Rename. You can open the catalog in either offline or online mode. In offline mode, you can rename all objects. In online mode, you might be unable to rename certain objects, depending on your permissions.

Caution:

Keep the following points in mind when renaming objects:

  • You cannot rename a user account in the catalog. If you rename a user's home directory, then you do not rename that user and you might see unexpected results.

  • The catalog contains several reserved names of objects. Rename only your own objects, not those that Presentation Services creates internally. For example, do not rename the _portal directory in your home directory, because then you cannot see "My Dashboard".

To rename an object without reference updates:

  1. In Catalog Manager, open the catalog.

  2. Navigate to the object to be renamed.

  3. Right-click the object in the Name column and select Rename.

  4. Type a new name for the object.

To rename an object with reference updates:

  1. In Catalog Manager, open the catalog in offline mode.

  2. Navigate to the object to be renamed.

  3. Right-click the object in the Name column and select Smart Rename.

  4. Type a new name for the object.

A progress bar in the lower-right corner of the window shows the progress of the reference updates.

16.6.4 Working with the Properties of Catalog Objects

Using the Properties option of Catalog Manager, you can:

  • Create, view, edit, and delete the properties of catalog objects.

  • Change attributes of catalog objects to hide them from display in Oracle Business Intelligence.

To work with the properties of a catalog object:

  1. In Catalog Manager, open the catalog.

  2. Navigate to the object.

  3. Right-click the object in the Name column and select Properties.

  4. Perform the necessary tasks:

    1. If you have the appropriate permissions, then select the appropriate owner for the object in the Owner list.

      The Owner list includes the name that you used to log in to Catalog Manager. You can use this list to select yourself as the owner of the object.

      See "Assigning Ownership of Objects" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition for more information on taking ownership of objects.

    2. To change the attribute of an object, select either Read-Only or Hidden, if appropriate. A hidden object is not visible in Oracle Business Intelligence.

      Note:

      The System option indicates that the object is maintained internally and should not be altered.

    3. To create, edit, or delete a property, use the New, Edit, or Delete button as appropriate.

      Note:

      The New button is used to create a property. Use it only if instructed to do so by Oracle Support Services.

  5. Click OK.

You can select multiple objects and update their properties or permissions simultaneously. If any of the selected objects are a folder, then you can also apply those changes recursively to all the objects in that folder's tree structure.

For example, you can set all files in the /shared/DontTouch directory to be Read-Only. Right-click the DontTouch directory and select Properties. In the Properties dialog, select the Read-Only option, select the Apply Recursively option, and click OK. You can also select Apply Recursively to take ownership of an object and all its sub-objects.

16.6.5 Setting Permissions of Catalog Objects

Permissions are used to control access to catalog objects.

To set permissions of a catalog object:

  1. In Catalog Manager, open the catalog.

  2. Navigate to the object.

  3. Right-click the object in the Name column and select Permissions.

    The Permissions dialog displays these two lists:

    • Users, Catalog Groups and Application Roles (Explicit Permissions) — Shows the users, groups, and application roles that have explicit permissions granted to this object.

    • Additional Users and Application Roles — Shows the users, groups, and application roles that have access granted through group inheritance, and users, groups, and application roles that have no access to the request.

    For details on how permissions and privileges are assigned in Presentation Services, see "Managing Security for Dashboards and Analyses" in Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition.

  4. If the user, group, or application role whose permissions you want to set is in the Additional Users and Application Roles list, then move it into the Users, Catalog Groups and Application Roles (Explicit Permissions) list by selecting it and clicking the left-arrow button (<).

  5. (Optional) To filter the users, groups, and application roles displayed in the Additional Users and Application Roles list, use the List button and the adjacent field, as follows:

    • Enter filter criteria in the field next to the List button (case insensitive) to search by name.

      To enter partial filter criteria, use the asterisk (*) symbol. For example, enter bi* to display users or groups beginning with bi, BI, bI, and Bi.

    • Select a value from the list, to restrict what accounts to search for.

      Available values are: All, User, Catalog Group, or Application Role.

  6. Select the user or group in the Users, Catalog Groups and Application Roles (Explicit Permissions) list.

  7. Select a new permission from the list in the Permissions column, or click Custom from the list to display the Custom Permissions dialog, where you can select a combination of permissions.

    For details on what each permission means, see "Permission Definitions" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

  8. Select the Apply Recursively option to apply the changes to all the objects that the object contains.

  9. Select a value from the Replace Option list as follows:

    • Replace All — Replaces the existing ACL with what is currently in the dialog.

    • Replace Listed — Changes only the accounts currently displayed in the dialog and leaves others unchanged.

    • Remove Listed — Removes only the accounts currently displayed and leaves others unchanged.

  10. Click OK.

Note:

If you move a user or group from the Users and groups (Explicit Permissions) list to the Additional Users and Application Roles list, then the user or group privileges are reset to No Access. To move a user or group from one list to another, highlight it and click the right or left-arrow button, as appropriate.

See Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition for more information about permissions and groups and users.

16.6.6 Previewing Objects from Catalog Manager

You can preview objects, such as analyses or prompts, from Catalog Manager in online mode. If you are going to preview objects from Catalog Manager, then you must identify the default browser in which to display these objects.

To set the browser preference:

  1. In Catalog Manager, from the Tools menu, select Preferences.

  2. In the Select Web Browser to use for report previews field, select the browser that is the same one that you have set to be the default browser for your operating system. You can click the Browse button in which you can select the executable file for the appropriate browser.

  3. Click OK.

To preview an object:

  1. In Catalog Manager, open the catalog in online mode.

  2. Navigate to the object.

  3. Right-click the object in the Name list and select Preview.

16.7 Viewing and Editing Catalog Objects in XML

Catalog Manager provides the ability to view and to edit the XML description of catalog objects such as analyses, dashboards, filters, and so on. While viewing the XML code is acceptable, editing the code is not recommended.

Caution:

If you edit the XML code, then you change the representation of the object in the catalog. Editing the XML code for catalog objects in any directory is not recommended and can produce unexpected results

If you want to edit the XML for an analysis, then use the information in "Examining the Logical SQL Statements for Analyses" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

To view the XML description of an object:

  1. In Catalog Manager, open the catalog.

  2. Navigate to the object.

  3. Right-click the object in the Name column and select Properties.

  4. Click Edit XML.

  5. When you have finished viewing the XML definition, click Cancel.

  6. Click OK in the Properties dialog.

Figure 16-3 shows sample XML code in Catalog Manager for an object.

Figure 16-3 Sample XML Code for an Object

Description of Figure 16-3 follows
Description of ''Figure 16-3 Sample XML Code for an Object''

To edit the XML description of an object, which is not recommended:

  1. In Catalog Manager, open the catalog.

  2. Navigate to the object.

  3. Right-click the object in the Name column and select Properties.

  4. Click Edit XML, then Edit.

  5. Make the changes in the Object XML area.

    Note:

    When you edit the XML description of an object, the catalog checks only that the XML is well-formed; it does not check for any other errors.

  6. Click OK in the Edit XML dialog.

  7. Click OK in the Properties dialog.

16.8 Searching for and Replacing Catalog Text Using Catalog Manager

You can search for specific text in the catalog and replace it with other text using Catalog Manager. You can open the catalog in either online or offline mode. In offline mode, you can replace all objects. In online mode, you might be unable to replace certain objects, depending on your permissions.

Specifically, you can search for and replace:

16.8.1 Searching for and Replacing a Simple Catalog Text String

Use the following procedure to search for a simple text string in the catalog and replace it with other text.

To search for and replace a simple text string:

  1. In Catalog Manager, open the catalog in either online or offline mode.

  2. From the Tools menu, select XML Search and Replace.

  3. In the Old text field, enter the text string to search for.

  4. In the Replace with field, enter the replacement text.

  5. To make the search case insensitive, deselect the Case Sensitive box.

  6. Click OK.

16.8.2 About Searching for and Replacing Multiple Catalog Text Strings

You can perform more powerful search and replace operations on multiple catalog text strings all at the same time by importing a XML file that identifies each text string to search for and replace.

16.8.2.1 XML File Format for Searching for and Replacing Text Strings

In the search and replace XML file, you use an action element to identify each text string to search for and replace. The action elements are contained in a commands element.

The action element has the following attributes:

  • command — Specifies the text to replace. The valid value is:

    • textReplace — Replaces all the text that matches in an XML file, such as a column name.

  • oldValue — Specifies the text string to search for.

    When you specify this attribute for the textReplace command for the search and replace XML file, you must use the full Java regex syntax, which is not like a normal string. To replace a string, you must do the following:

    1. Escape any special Java regex characters (such as brackets, parentheses, dollar signs, and carets).

    2. Escape any special "normal" string characters (such as back slashes and quotes).

    3. Because you are working in an XML file, escape any special HTML characters (such as quotes and ampersands).

    The full Java regex syntax is described in the following document:

    http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html">>http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html

    Table 16-2 provides sample strings for use with the regex syntax in search criteria.

    Table 16-2 Sample Strings For Use With Regex Syntax in Search Criteria

    Search String Entered Result

    a

    Adds wildcards before and after your search string (for example, *a*), enabling the search to return results that contain the letter "a".

    ^a

    Adds a wildcard after your search string (for example, a* ), enabling the search to return results that begin with the letter "a".

    a$

    Adds a wildcard before your search string (for example, *a ), enabling the search to return results that end with the character "a".

    a\*

    Searches explicitly for strings containing a character followed by an asterisk (*) for example, "a*".

    ?

    Use a question mark (?) with a character and an asterisk (*) to return zero (0) or more occurrences of a character. For example ?a* returns zero or more occurrences of the character "a".

  • newValue — Specifies the replacement text.

  • ignoreCase — Ignores case when set to true, but becomes case-sensitive when set to false. The default value is false.

16.8.2.2 Example XML File for Searching for and Replacing Text Strings

The following is a partial example of an XML file for searching for and replacing a text string:

<?xml version="1.0" encoding="utf-8"?>
<actions>
<action command="textReplace" oldValue="boots" newValue="HoleyShoes" ignoreCase="true"/>
</actions>

16.8.3 Searching for and Replacing Multiple Catalog Text Strings

Use the following procedure to search for and replace multiple catalog text strings all at the same time.

To search for and replace multiple text strings:

  1. Create the XML file for searching for and replacing multiple text strings.

    For information, see Section 16.8.2, "About Searching for and Replacing Multiple Catalog Text Strings."

  2. In Catalog Manager, open the catalog in offline mode.

  3. From the Tools menu, select XML Search and Replace.

  4. In the Import from File field, enter the path or click Browse to specify the XML file that you created in Step 1.

  5. To make the search case-sensitive, select the Case Sensitive box.

  6. Click OK.

16.9 Creating Reports to Display Catalog Data Using Catalog Manager

You can create reports to display catalog data for all catalog object types. You can either display the report on the screen or save it to a file. When you create a report, a blank or empty field is exported as a tab character. If you create a report with the default of a tab as the field separator, then two tab characters in the report file indicate a blank field.

To create a report that displays catalog data:

  1. In Catalog Manager, open the catalog. To create a report that shows the SQL statement that is sent to the Oracle BI Server for the object, open the catalog in online mode.

  2. Select the top folder for the catalog.

  3. From the Tools menu, select Create Report.

  4. Select the catalog object type for which you want to create a report.

  5. To eliminate any rows that are the same from the report, select the Distinct box.

  6. Specify the columns to be displayed in the report in the Columns in Report list. Use the left and right-arrow buttons (< and >) to move the columns between the Available Columns list and the Columns in Report list, and the plus and minus buttons (+ and -) to set the order in which columns are displayed in the report.

  7. Click OK.

  8. Repeat Steps 4 through 7 until the report contains the appropriate columns.

  9. To save the report to a file, in the Save report to field, specify the path name of the file. Click the Browse button to display the Save As dialog for selecting the path name (if the file does not exist, then it is created).

  10. Select Excel Format to specify to create a file with a .tab extension that can be imported into Microsoft Excel.

    For details on supported Excel versions as part of Microsoft Office, see the system requirements and certification documentation. For information, see Section 1.9, "System Requirements and Certification."

  11. Click OK.

16.9.1 Sample Uses for Reports

You can generate reports for various purposes, as described in the following examples:

  • To see which dashboards are using an analysis, you can run a Dashboard report including analyses, and search that report for the analysis

  • To find analyses that are affected by a changed column in a repository table, you can run an Analysis report that includes all columns and formulas, and then search the report for the items that must then be replaced in Catalog Manager.

  • You can create a report that displays all the dashboard prompts and related fields (such as column, formula, and subject area) within the dashboards. You can also create a report of analyses and extract the filters that are used within those analyses. The following is an example of extracting filters in which the formula is derived using a saved filter that is prompted:

    Example: "Markets"."Region" [Filter, prompted]

  • You can create a report that displays the ACLs for objects. By reviewing the ACLs in the report, you can verify that access to objects is granted to the proper roles with the proper permissions, such as Read/Write. The following line shows an example of ACLs in the report:

    "^biconsumer=RX:*MyCatalogGroup=RWX:steve=F", where the caret (^) indicates an Application Role, the asterisk (*) indicates an internal catalog group, and "nothing" indicates a user.

16.10 Archiving and Unarchiving Using Catalog Manager

Catalog Manager provides the ability to archive and unarchive either an individual catalog folder or an entire catalog. See the following list for important information on this functionality:

  • When you archive an individual catalog folder, all objects in the folder and the folder's subfolders are saved in single compressed file. Properties and attributes of objects are included in the archive file.

  • When you unarchive an individual catalog folder, the archive file is uncompressed and all objects in the folder and the folder's subfolders are then stored in the current offline catalog. Existing folders that have the same names as folders being unarchived are overwritten without warning.

  • Archiving and unarchiving an entire catalog using Catalog Manager or the Catalog page in Presentation Services is not recommended. Instead, use either the 7-Zip utility or .tar.gz files on UNIX systems for archiving and unarchiving an entire catalog.

  • Do not archive an entire catalog by starting at the root level (\). Always specify specific folder names when archiving.

  • Do not use the following utilities when archiving and unarchiving an entire catalog:

    • WinZip — The WinZip utility does not always handle extended UNIX file permissions properly. Using the WinZip utility to move catalogs in heterogeneous environments might lead to corrupted catalog files.

    • FTP — Some third-party FTP programs rename internal files, which might lead to corrupted catalog files. Before moving a catalog using an FTP program, use the 7-Zip utility to compress the catalog into one file.

You can use the Catalog page in Presentation Services to archive and unarchive objects. For information, see "Archiving Objects" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

16.10.1 Archiving a Folder Using Catalog Manager

Use the following procedure to archive a catalog folder.

To archive an individual catalog folder in the catalog to a file that you specify:

  1. In Catalog Manager, open the catalog in offline mode.

  2. Highlight the catalog folder and from the File menu, select Archive.

  3. In the Archive File Path field, specify the path name of the file in which to archive the folder. Click Browse to display a dialog for selecting the path name.

  4. To archive the:

    • Timestamps that are assigned to the objects and folders that you are archiving, then select the Keep file time stamps option.

      If you do not select this option, then the archiving process does not include timestamp information and the Old option in the Paste Overwrite area of the Preferences dialog is ignored. Upon unarchiving, the system applies a timestamp that indicates the time at which the object or folder is unarchived.

      See Section 16.6.2.2, "Advanced Options for Pasting Objects" for more information.

    • Permissions that are assigned to each object or folder, then select the Keep permissions option.

      If you do not select this option, then the archiving process does not include any permissions and the options in the Paste ACL area of the Preferences dialog are ignored. Upon unarchiving, the system assigns the parent folder's permissions to all of the objects and folders.

  5. Click OK.

16.10.2 Unarchiving a Folder Using Catalog Manager

Unarchiving is similar to pasting and therefore requires that you understand the issues that relate to permissions and ACLS as described in Section 16.6.2.2, "Advanced Options for Pasting Objects." Use the following procedure to unarchive a catalog folder.

To unarchive a catalog folder:

  1. In Catalog Manager, open the catalog in offline mode.

  2. To unarchive a catalog folder, navigate to the location where you want to unarchive the folder.

  3. From the File menu, select Unarchive.

  4. In the Archive File Path field, specify the path name of the catalog folder to unarchive. Click Browse to display a dialog for selecting the path name.

  5. Click OK.