Skip Headers
Oracle® Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
11g Release 1 (11.1.1)

Part Number E10541-07
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

17 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:

17.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:

17.1.1 Objects in the Catalog

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

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

Description of Figure 17-1 follows
Description of "Figure 17-1 Sample Objects in the Catalog in Presentation Services"

17.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 17.1.3, "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"\?
    

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

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

17.1.2 Locations for the Catalog

The following list provides the default locations for the directory that holds catalog files:

  • On Windows systems:

    ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\catalog

  • On UNIX systems:

    ORACLE_INSTANCE/bifoundation/OracleBIPresentationServicesComponent/coreapplication_obipsn/catalog

You are not required to store the catalog in its default location. You can store the catalog in other locations. When you work in a cluster configuration, you store the catalog on a shared file system that all nodes in the cluster can access. For information, see Section 5.4.3, "Sharing the Oracle BI Presentation Catalog."

See Section 17.1.3.3, "Handling Catalog Files on Various Platforms" for more information on catalog directory names.

17.1.3 File System Guidelines for Catalogs

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

17.1.3.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. In Release 11g, 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. Before you modify the element, ensure that you are familiar with the information in Section 3.4, "Using a Text Editor to Update Configuration Settings."

17.1.3.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".

17.1.3.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 17.2.1, "Manually Changing Additional 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 17.2.1, "Manually Changing Additional 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.

17.1.3.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 patches. Obtain key patches to update older versions of Oracle BI EE as necessary.

    For more information, see Section 17.2.5, "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.

17.2 Maintaining the Oracle BI Presentation Catalog

This section contains the following topics on maintaining a catalog:

17.2.1 Manually Changing Additional Configuration Settings for the Catalog

In addition to the presentation settings that you can change in Fusion Middleware Control, you can modify other settings manually. Use various elements in the instanceconfig.xml file to change these settings.

Before you begin this procedure, ensure that you are familiar with the information in Section 3.4, "Using a Text Editor to Update Configuration Settings".

To manually change additional configuration settings for the catalog:

  1. Open the instanceconfig.xml file for editing as described in Section 3.6, "Where Are Configuration Files Located?"

  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:

    • The HashUserHomeDirectories element must be set immediately after installing Oracle BI EE to be effective.

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

17.2.2 Manually Creating a New Oracle BI Presentation Catalog

You can manually create a new catalog.

To manually create a new catalog:

  1. Stop the service for Presentation Services.

    The Oracle BI Server and WebLogic Server must be running.

  2. Specify a new location (one that does not exist) for the catalog on the Repository tab of the Deployment page in Fusion Middleware Control.

    See Section 10.2, "Using Fusion Middleware Control to Upload a Repository and Set the Oracle BI Presentation Catalog Location."

  3. Ensure that the new location for the catalog is empty.

  4. Save your changes and close the file.

  5. Restart Presentation Services.

When manually creating a new catalog in a clustered environment, you must restart each instance of Presentation Services separately using the Availability tab of the Capacity Management page in Fusion Middleware Control. Do not click Restart on the Business Intelligence Overview page. Wait a short time after restarting the first Presentation Services instance to give the system enough time to create the new catalog, then verify that the catalog was successfully created in the Presentation Services log file before restarting the other Presentation Services instances in the cluster.

17.2.3 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:

17.2.3.1 Deploying Catalogs to Production

Use the 7-Zip utility to archive an entire catalog in a test environment, then use the utility to unarchive the file in the production environment. Do not use Catalog Manager for archiving and unarchiving entire catalogs.

You might deploy a catalog in a cluster configuration in which different security environments are used. Some servers in the cluster might share the same LDAP server, while others might not. If you deploy the catalog to a server that is communicating with a different LDAP server, then you must refresh the user GUIDs for the catalog. See "Refreshing User GUIDs" in Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition for information.

Optionally, if you are deploying the catalog from test to a new production environment, then use Fusion Middleware Control to specify the location of the new catalog in the production environment. For information, see Section 10.2, "Using Fusion Middleware Control to Upload a Repository and Set the Oracle BI Presentation Catalog Location."

17.2.3.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 17.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.

  3. (Optional) If you are deploying the catalog from test to a new production environment, then use Fusion Middleware Control to specify the location of the new catalog in the production environment.

    For information, see Section 10.2, "Using Fusion Middleware Control to Upload a Repository and Set the Oracle BI Presentation Catalog Location."

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

  • Use this option only if you know that no security changes have occurred on the system. If changes have occurred for example with global unique identifiers (GUIDs), then use the procedure that is described in "Refreshing User GUIDs" in Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition.

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.

17.2.5 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:

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

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

17.2.5.3 Important Guidelines for Validating the Catalog

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

  • You must refresh the user GUIDs before validating the catalog. If you attempt to validate a catalog whose user GUIDs are not synchronized, then the validation process assumes that all accounts have been deleted and effectively removes all account information from the catalog.

    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.

17.2.5.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 4.3, "Using Fusion Middleware Control to Start and Stop Oracle Business Intelligence System Components and Java Components."

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

  3. Refresh the user GUIDs for the catalog. See "Refreshing User GUIDs" in Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition for information.

    Caution:

    Ensure that you refresh the user GUIDs before validating the catalog. Failure to do so can result in the removal of all accounts, permissions, and privileges from the catalog.

  4. Create a backup copy of the instanceconfig.xml file.

    For the location of the file, see Section 3.6, "Where Are Configuration Files Located?"

  5. 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 17.2.5.5, "Specifying the Elements for Validating the Catalog."

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

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

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

  9. Stop Presentation Services.

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

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

  12. Start Presentation Services.

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

Before you begin this procedure, ensure that you are familiar with the information in Section 3.4, "Using a Text Editor to Update Configuration Settings."

To specify the element for validating the catalog:

  1. Open the instanceconfig.xml file for editing as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Locate the Catalog section in which you must add the elements that are described in Table 17-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 17-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:

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

17.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 15.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.

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

17.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 15.3, "Setting the Current Locale in Catalog Manager."

17.4 Starting Catalog Manager and Opening Catalogs

This section describes the following topics:

17.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 32-bit and 64-bit

    • Linux 32-bit and 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

17.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:

    ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\catalogmanager

    then run the appropriate script:

    runcat.cmd (on Windows)

    runcat.sh (on Linux)

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

Figure 17-2 Sample Objects in Catalog Manager for Windows

Description of Figure 17-2 follows
Description of "Figure 17-2 Sample Objects in Catalog Manager for Windows"

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

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

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

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

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

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

      C:\ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\catalog\default

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

17.5 Using the Catalog Manager Workspace

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

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

17.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.)

17.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.)

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

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

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

17.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 17.6.2.2, "Advanced Options for Pasting Objects."

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

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

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

17.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.)

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

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

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

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

17.6.7 Working with Tenants

Catalog Manager provides options for provisioning and unprovisioning tenants. For complete information, see Chapter 18, "Configuring for Multiple Tenants."

17.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 17-3 shows sample XML code in Catalog Manager for an object.

Figure 17-3 Sample XML Code for an Object

Description of Figure 17-3 follows
Description of "Figure 17-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.

17.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:

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

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

17.8.2.1 XML File Format for Searching for and Replacing Text Strings

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

The action element has the following attributes:

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

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

  • oldValue — Specifies the text string to search for.

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

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

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

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

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

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

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

    Table 17-2 Using 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.

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

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

17.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.8, "System Requirements and Certification."

  11. Click OK.

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

17.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:

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.

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

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

17.11 Overview of Configuring for Full-Text Catalog Search

As the administrator, you can configure a search engine to crawl and index the Oracle BI Presentation Catalog. With this configuration, you provide content designers and users with the ability to perform a full-text catalog search for objects and attachments.

This section contains the following topics:

Note:

You can use the full-text catalog search functionality to search in most catalog objects and related documents. Currently, the full-text catalog search functionality searches in scorecards themselves and in the names of related documents, but it does not search in the content of related documents for scorecards.

For information about content designers and users using the full-text catalog search, see "Searching for Objects in the Catalog" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

17.11.1 What Is a Full-Text Catalog Search?

The full-text catalog search provides a mechanism for searching for objects in the Oracle BI Presentation Catalog that is similar to a full-text search engine. This full-text search provides more advanced options than the basic catalog search that Presentation Services provides, as described in the following list:

  • Basic Catalog Search — Users can search for an object by its exact name, which is similar to using a Find dialog in many products.

  • Full-text Catalog Search — Users can search for objects by various criteria, such as name, description, author, and the names and values of columns of data that the object references. Users obtain search results that correspond to the objects that they have access to open.

For more information on the types of searches, see "How Can I Search for Objects?" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

17.11.2 How Is Security Handled in the Full-Text Catalog Search?

The search engine enforces all the security that is defined on the Oracle BI content. Security for Oracle BI content can be defined at the object level, enforced through folder level security on the Oracle BI Server, and at the data level, enforced at runtime or query time through user variables that are used to constrain the data.

In addition, the Do Not Index setting in the Properties dialog for an object affects whether the object can be indexed.

See Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition for details on security.

17.11.3 What Search Engines Are Supported?

As the administrator, you must configure the use of the full-text catalog search. For this release, the full-text catalog search uses the following engines, which provide crawling and indexing of the Oracle BI Presentation Catalog. The index that the engine creates is used by the full-text catalog search for locating objects for which users are searching.

17.12 Configuring for Searching with Oracle Secure Enterprise Search

Note:

Before reading this section, ensure that you familiar with Section 17.11, "Overview of Configuring for Full-Text Catalog Search."

You can configure the system to use Oracle Secure Enterprise Search (Oracle SES) as the search engine for full-text searching. The full-text catalog search can use a crawler to index catalogs that contain translated text. Oracle SES limits each of its registered sources to a single locale. Therefore, a multilingual translated Oracle BI Presentation Catalog can be indexed only in a single language. The user interface for Oracle SES supports multiple languages.

You must configure the use of the full-text catalog search with Oracle SES, as described in the following sections:

  1. "Step 1: Assigning Privileges for Crawling and Indexing"

  2. "Step 2: Ensuring that Oracle Secure Enterprise Search Is Available"

  3. "Step 3: Configuring Identity Management for Full-Text Catalog Search"

  4. "Step 4: Creating the Data Source for Full-Text Catalog Search"

  5. "Step 5: Editing the Schedule for Full-Text Catalog Search"

  6. "Step 6: Enabling Incremental Crawls for Full-Text Catalog Search"

  7. "Step 7: Configuring Properties for Full-Text Catalog Search Manually"

  8. "Step 8: Enabling SSL for the Full-Text Catalog Search"

17.12.1 Step 1: Assigning Privileges for Crawling and Indexing

The process of crawling and indexing the Oracle BI Presentation Catalog is initiated from the search engine. However, the catalog cannot be crawled and indexed unless a user with administrator privileges grants the BISystem application role the appropriate privileges within Oracle BI Presentation Services.

For information, see Section 17.14.1, "Assigning Privileges for Searching."

17.12.2 Step 2: Ensuring that Oracle Secure Enterprise Search Is Available

The files that are required to use the full-text catalog search are copied to the appropriate directories during the installation of Oracle BI EE. Users cannot access the full-text catalog search if a supported search engine is not installed and configured for use with the Oracle BI Presentation Catalog.

For details on which version of Oracle SES to use with this release of Oracle BI Enterprise Edition, see Section 1.8, "System Requirements and Certification." You can install Oracle SES either before or after you install Oracle BI EE and on either the same computer or a different one.

For information about Oracle SES, display the following page from Oracle Technology Network:

http://www.oracle.com/us/products/database/secure-enterprise-search/index.html

Before proceeding, ensure that Oracle SES is installed at your site and that you know the URL to the Oracle SES administration tool. You use the administration tool to configure crawling and indexing of the Oracle BI Presentation Catalog. Use a URL in the following format to access the administration tool:

http://host:port/search/admin/control/login.jsp

where host is the computer on which Oracle SES is installed and port is the port for the administration tool.

17.12.3 Step 3: Configuring Identity Management for Full-Text Catalog Search

This procedure does not apply if you installed Oracle BI EE as part of Oracle Fusion Applications.

Use the Oracle SES administration tool to configure identity management for the full-text catalog search.

To configure Identity Management for the full-text catalog search:

  1. Access the Oracle SES administration tool.

  2. Display the Identity Management Setup page using steps such as the following:

    Select Global Settings, then Identity Management Setup in the System section.

  3. In the list of available identity plug-ins, select Oracle Fusion and click Activate.

  4. On the Activate Identity Plug-in tab, specify the following:

    • HTTP endpoint for authentication: The URL for the full-text catalog search security service, in the following format:

      http://host:port/bisearch/crawler/SecurityService

      where host is the name of the computer on which Oracle Business Intelligence is installed and port is the number of the port that is used by the search application of Oracle Business Intelligence.

    • User ID: The ID of a valid Oracle Business Intelligence user that performs the crawl.

    • Password: The password of the user.

  5. Click Finish.

17.12.4 Step 4: Creating the Data Source for Full-Text Catalog Search

Use the Oracle SES administration tool to configure the Oracle BI Presentation Catalog as a source that can be crawled and indexed.

To configure the data source for the full-text catalog search:

  1. Access the Oracle SES administration tool.

  2. Select the Home tab, then the Sources tab.

  3. In the Source Type list, select Oracle Fusion, then click Create.

  4. On the Source Configuration tab, specify the following:

    • Name: Enter a name for the data source.

    • Configuration URL: The URL for the configuration file for the full-text catalog search, in the following format:

      http://host:port/bisearch/crawler/oracle.biee.search.BISearchableTreeObject/ConfigFeed?forceInitialCrawl=true

      where host is the name of the computer on which Oracle Business Intelligence is installed and port is the number of the port that is used by the search application of Oracle Business Intelligence.

    • Authentication Type: The type of authentication for users. Select the default value of Native, which enables the full-text catalog search to handle authentication.

    • User ID: The ID of a valid Oracle Business Intelligence user that performs the crawl.

    • Password: The password of the user.

    • Realm: Leave this blank.

    • Scratch Directory: Specify a temporary existing directory where Oracle SES can store temporary files.

    Click Next.

  5. On the Authorization tab, specify the following:

    • Authorization: Select ACLs Controlled by the Source.

    • HTTP endpoint for authorization: The URL for the full-text catalog search security service, in the following format:

      http://host:port/bisearch/crawler/SecurityService

      where host is the name of the computer on which Oracle Business Intelligence is installed and port is the number of the port that is used by the search application of Oracle Business Intelligence.

    • User ID: The ID of a valid Oracle Business Intelligence user that performs the crawl.

    • Password: The password of the user.

    • Business Component: Enter the following value: oracle.biee.search.BISearchableTreeObject

    • Display URL Prefix: The URL for the search functionality in Oracle BI EE, in the following format:

      http://host:port/bisearch/urlbuilder/

      where host is the computer on which Oracle BI Enterprise Edition is installed and port is its port number.

  6. Click one of the following:

    • Click Create to automatically launch the schedule.

    • Click Create and Customize to perform any customizations, such as including additional documents to be processed (for example, RTF documents), as described in the next step.

  7. If you clicked Create and Customize, then on the Documents tab, add the RTF Document document type and any other appropriate types to the "Processed" document types list.

  8. Click Apply.

17.12.5 Step 5: Editing the Schedule for Full-Text Catalog Search

When you create a data source in the Oracle SES administration tool for the Oracle BI Presentation Catalog, a schedule for crawling and indexing of that source is created automatically. You can use the administration tool to edit the schedule. For information on the types of crawls, see Section 17.14.2, "Understanding Crawling and Data Loading."

17.12.6 Step 6: Enabling Incremental Crawls for Full-Text Catalog Search

For incremental crawls to occur, you must enable replication as described in Section 17.14.3, "Enabling Incremental Crawls or Data Loads."

After you have enabled replication, use a URL in the following format to start an incremental crawl by Oracle SES. Include false at the end of the URL to perform an incremental crawl, and include true at the end to perform a full crawl.

http://host:port/bisearch/crawler/oracle.biee.search.BISearchableTreeObject/ConfigFeed?forceInitialCrawl=false

17.12.7 Step 7: Configuring Properties for Full-Text Catalog Search Manually

You must manually configure properties for searching with Oracle SES, as described in Section 17.14.5, "Configuring Properties Manually for Searching."

17.12.8 Step 8: Enabling SSL for the Full-Text Catalog Search

To enable Secure Socket Layer (SSL) to be used with the full-text catalog search:

  1. Enable SSL for Oracle Business Intelligence, as described in "Configuring SSL Communication Between Components" in Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition.

  2. Enable SSL in Oracle SES, as described in "SSL and HTTPS Support in Oracle Secure Enterprise Search" in Oracle Secure Enterprise Search Administrator's Guide.

  3. Configure an Oracle SES identity that uses the https address for the security service of the full-text search, as described in "SSL and HTTPS Support in Oracle Secure Enterprise Search" in Oracle Secure Enterprise Search Administrator's Guide.

  4. Create a data source that uses the https address for the full-text search and run the crawl, as described in Section 17.12.4, "Step 4: Creating the Data Source for Full-Text Catalog Search."

17.12.9 Step 9: Enabling Users to Access the Full-Text Catalog Search

When you have configured Oracle SES to crawl and index the Oracle BI Presentation Catalog, you can notify content designers and users that the full-text catalog search is available. Use the following procedures to make the full-text search available to content designers and end users:

17.12.9.1 Configuring the BI Search Application for Full-Text Search

When you install Oracle BI EE, files related to the full-text search are installed and configured. You must use the following procedure to configure the BI Search Application to display full-text search results to users.

To configure the BI Search Application for full-text searching:

  1. Using Fusion Middleware Control Console, create a user called bisearchws_user.

  2. In Fusion Middleware Control, select WebLogic Domain, then bifoundation_domain.

  3. Select WebLogic Domain, Security, and Credentials.

  4. On the Credentials page, select the oracle.bi.system credential map and click Create Key.

  5. In the Create Key dialog, enter the bisearchws_user user name and its password and click OK.

  6. Select WebLogic Domain, Security, and System Policies.

  7. On the System Policies page, change the policy type to Codebase, select Includes in the Name list, enter bisearch for the name, and click Search.

  8. Select the line that is returned and click Edit.

  9. On the Edit System Grant page, click Add.

  10. In the Add Permission dialog:

    1. Select Select here to enter details for a new permission.

    2. In the Permission Class box, enter the following:

      oracle.security.jps.service.credstore.CredentialAccessPermission

    3. In the Resource Name box, enter the following:

      context=SYSTEM,mapName=oracle.bi.system,
      keyName=bisearchws_user

    4. In the Permission Actions box, enter a single asterisk (*).

    5. Click OK twice.

  11. Update the BISearchConfig.properties file with the following values:

    • SES_AdminServiceURL = http://$SES_INSTANCE:$SES_PORT/search/ws/admin/SearchAdmin

    • SES_QueryServiceURL = http://$SES_INSTANCE:$SES_PORT /search/query/OracleSearch

    • SES_QueryProxyUserKey = bisearchws_user

    • ECSF_DataServiceURL = http://$BI_INSTANCE:$BI_PORT/bisearch/crawler

    • ECSF_SecurityServiceURL = http://$BI_INSTANCE:$BI_PORT /bisearch/crawler/SecurityService

    • ECSF_RedirectServiceURL = http://$BI_INSTANCE:$BI_PORT /bisearch/crawler

    See Section 17.12.7, "Step 7: Configuring Properties for Full-Text Catalog Search Manually" for more information.

  12. Create a data source in Oracle SES that is configured to crawl the Oracle Business Intelligence instance, then crawl the instance.

    See Section 17.12.4, "Step 4: Creating the Data Source for Full-Text Catalog Search" for more information.

  13. Create a search group in Oracle SES for Oracle Business Intelligence using the data source that you created in the previous step.

    You use the name of this group in the <SearchGroup> element that you modify when "Editing the Configuration File to Enable Search".

  14. Edit the instanceconfig.xml, as described in Section 17.12.9.1.1, "Editing the Configuration File to Enable Search."

  15. Create a federated user in Oracle SES using the following steps:

    1. Access the Oracle SES administration tool.

    2. Display the Global Settings tab.

    3. Click the Federation Trusted Entities link in the Search section.

    4. On the Federation Trusted Entities page, enter bisearchws_user as the Entity Name, select Use Identity Plug-in for authentication, and click Add.

  16. Restart Oracle Business Intelligence as described in Section 4.3, "Using Fusion Middleware Control to Start and Stop Oracle Business Intelligence System Components and Java Components."

17.12.9.1.1 Editing the Configuration File to Enable Search

You must manually edit the configuration file for Oracle BI EE (called instanceconfig.xml) to include the appropriate elements, as described in Section 17.14.4, "Editing the Configuration File for Searching."

17.13 Configuring for Searching with Oracle Endeca Server

Note:

Before reading this section, ensure that you familiar with Section 17.11, "Overview of Configuring for Full-Text Catalog Search."

You can configure the system to use Oracle Endeca Server as the search engine for full-text searching. In this release, only the English language is supported and you must use Secure Socket Layer mutual authentication between Oracle Endeca Server and Oracle Business Intelligence. The complete documentation set for Oracle Endeca Server is available at the following location:

http://docs.oracle.com/cd/E35822_01/index.htm

When you configure Oracle Endeca Server as the search engine for full-text searching, you can use attributes in Presentation Services. You can use attributes to filter and browse the search results. See "What Results Are Returned from a Full-Text Catalog Search?" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition for information on attributes.

For details on which version of Oracle Endeca Server to use with this release of Oracle BI Enterprise Edition, see Section 1.8, "System Requirements and Certification." You cannot use Oracle Endeca Server in a clustered configuration with the full-text catalog search.

You must configure the use of the full-text catalog search with Oracle Endeca Server, as described in the following sections:

  1. Section 17.13.1, "Step 1: Installing Oracle Endeca Server"

  2. Section 17.13.2, "Step 2: Assigning Privileges for Using Oracle Endeca Server"

  3. Section 17.13.3, "Step 3: Creating the Data Store for Full-Text Catalog Search"

  4. Section 17.13.4, "Step 4: Enabling Data Loading for Full-Text Catalog Search"

  5. Section 17.13.5, "Step 5: Configuring Properties for Full-Text Catalog Search Manually"

  6. Section 17.13.6, "Step 6: Editing the Configuration File to Enable Search"

  7. Section 17.13.7, "Step 7: Enabling SSL for the Full-Text Catalog Search"

  8. Section 17.13.8, "Step 8: Enabling Users to Access the Full-Text Catalog Search"

17.13.1 Step 1: Installing Oracle Endeca Server

You must install Oracle Endeca Server before you can configure for full-text catalog search. For installation instructions, see Oracle Endeca Server Installation Guide at the following location:

http://docs.oracle.com/cd/E35822_01/server.740/es_install/toc.htm

After installing, ensure that Oracle Endeca Server has been started. You need Oracle Endeca Server running while you perform the other steps in this procedure. You can start the Oracle Endeca Server either from the Start Menu (on Windows) or with a script (on Linux). To start Oracle Endeca Server with a script, navigate to the Endeca Server install root directory, then to the endeca-server directory. Run the start.sh script.

For information on starting Oracle Endeca Server, see Oracle Endeca Server Administrator's Guide at the following location:

http://docs.oracle.com/cd/E35822_01/server.740/es_admin/toc.htm

17.13.2 Step 2: Assigning Privileges for Using Oracle Endeca Server

The process of using Oracle Endeca Server with the Oracle BI Presentation Catalog involves configuring certain privileges. Loading data and indexing the Oracle BI Presentation Catalog are initiated from the search engine. However, the process cannot occur unless a user with administrator privileges gives the appropriate privileges to the BISystem application role.

To receive notifications about data loading operations, the user who performs the operations must be granted the following privileges within Oracle BI Presentation Services:


Access: Access to Delivers
Actions: Create Navigate Actions
Actions: Create Invoke Actions
Delivers: Create Agents

For information, see Section 17.14.1, "Assigning Privileges for Searching."

17.13.3 Step 3: Creating the Data Store for Full-Text Catalog Search

You must create a data store before data can be loaded from the Oracle BI Presentation Catalog. The Dgraph process of the Endeca Server indexes the data. (The Dgraph process for the data store runs automatically when the data store is started using endeca-cmd command on the computer for Oracle Endeca Server.) You specify the name of the data store in the MDEXDataSourceName property of the BISearchConfig.properties file.

To create the data store:

  1. On the computer on which Oracle Endeca Server is running, open a command window and change to the endeca-cmd directory.

    The endeca-cmd directory contains the endeca-cmd script for running the Endeca Server commands. To run the commands, you use a command-line window (for example, open a Command Prompt in Windows) and navigate to the endeca-cmd directory, or run /path/endeca-cmd.

  2. Enter the following command:

    endeca-cmd create-ds bisearch

    This command creates the data store, which is called "bisearch," and automatically assigns a port number to the data store in a range that starts at 7770.

    You can instead enter the command so that you explicitly assign both the WS port and the Bulk Load port numbers, for example:

    endeca-cmd create-ds bisearch --ws-port 6060 --bulk-load-port 6061

    The Bulk Load port is used for loading data into Oracle Endeca Server, using the Bulk Ingest Interface. The WS port is the port that is used for sending any web service requests to the Oracle Endeca Server, which has interfaces in the form of web services. The full-text catalog search does not use the port to access the web services of Oracle Endeca Server. Instead, the full-text catalog search uses the same port that Oracle Endeca Server starts with, which has a default value of 7770. You can omit the ws-port from the command because if it is not specified, the port is assigned a number in the default range that specified on the Oracle Endeca Server.

  3. When the command completes, enter the following command to check the status of the data store:

    endeca-cmd status-ds bisearch

    You see output such as the following:

    WS Port: 6060
    Bulk Load Port: 6061
    Startup Timeout (s): 60
    Shutdown Timeout (s): 60
    

    In a later step of the process for configuring for searching, you specify the Bulk Load Port number as the value for the MDEXBulkLoadPort property in the BISearchConfig.properties file. For information, see Section 17.13.5, "Step 5: Configuring Properties for Full-Text Catalog Search Manually."

17.13.4 Step 4: Enabling Data Loading for Full-Text Catalog Search

After creating the data store, you perform a data load to enable searches of the Oracle BI Presentation Catalog using Oracle Endeca Server. (In Oracle SES, "crawling" is comparable to "data loading".)

You perform full and incremental data loads by creating and running agents. You can create multiple agents that perform data loads, but only one data load of the catalog can run at one time. You can set scheduling options for the agents to specify when the data loads are performed. You can set delivery options for the agents to send you an email when data loads have started and completed successfully or failed. The email that indicates that the data load has started includes a link that you can click to stop the load, if you read the email before the load completes. The email that indicates that the load has completed includes various statistics about the objects.

For descriptions of full and incremental data loads, see Section 17.14.2, "Understanding Crawling and Data Loading.". Incremental data loads occur only if you enable replication and perform a full data load, as described in Section 17.14.3, "Enabling Incremental Crawls or Data Loads."

As a data load progresses, the following details are stored in log files for Oracle Business Intelligence:

  • Statistics such as the number of objects retrieved and indexed.

  • Errors that occur during the data load, including those that cause the data load to fail.

After the data load is completed, the Dgraph process for that data store on Oracle Endeca Server begins handling search-type requests from users, based on the indexed results loaded into the data store. The Dgraph process is the internal process of the Oracle Endeca Server that runs when you start the data store in the Oracle Endeca Server. The Dgraph process runs queries against the data store and returns results to the end users, through the interfaces of the Oracle Endeca Server.

The process of data loading involves creating a device and creating agents, as described in the following sections.

17.13.4.1 Creating a Device for Emails on Data Loading

Before you can perform data loads, you must configure delivery options and a device for the user who runs the loads.

To create a device for emails for data loading:

  1. Log into Presentation Services as the user who runs the data loads.

  2. In the global header, click Signed In As username and select My Account.

  3. On the Delivery Options tab in the Devices section, create a device with the following values:

    • Name = BISearch

    • Category = Email

    • Device Type = HTML Email

    • Address/Number = The email address of the person who runs the data loads

  4. Click OK.

  5. Create a delivery profile with a name of High Priority and select High as the priority for the BISearch device.

  6. Click OK twice.

For more information, see "My Account dialog" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

17.13.4.1.1 Creating Agents for Data Loading

After you have created a device and delivery profile for emails, you can create agents for performing the data loads.

To create an agent for data loading:

  1. Log into Presentation Services as the user who runs the data loads.

  2. From the Home page, select New, then Agent.

  3. On the General tab of the Agent editor, set Priority to High and Run As to the Specified user who runs the data loads.

  4. On the Schedule tab, if a schedule is required, then specify when you want the agent to run.

  5. On the Recipients tab, select the user who runs the data loads and any other users who must be notified of data loads as recipients of the agent.

  6. On the Destinations tab, select Home Page and Dashboard and Active Delivery Profile as the Device.

  7. On the Actions tab, perform the following steps:

    1. Click the Add New Action button to create an action in the Agent Condition True or No Condition Exists section that invokes a web service.

    2. In the Select Web Service Operation dialog, enter the following value in the WSDL URL field. BISearchMDEXService is a SOAP web service that crawls and indexes the catalog and stores the indexing information in the Oracle Endeca Server.

      http://server-name:server-port/bisearch/BISearchMDEXService?wsdl

    3. Click Open to display a window that contains a directory.

    4. Double-click the BISearchMDEXCrawler_WSService directory, then double-click the BISearchMDEXService directory, and select the directory that is called Crawl.

  8. In the New Action dialog, specify the following parameter values. The specification of certain properties is optional when the properties have a default value that is set in the BISearchConfig.properties file.

    • crawl__excludePaths — Optionally specify the directories from the catalog from which data is not loaded. Delimit directories with a semicolon (;). This value overrides the value of the ExcludePaths property in the BISearchConfig.properties file.

    • crawl_fullCrawl — Specify "true" to perform a full data load or "false" for an incremental data load.

    • crawl_ibotPath — Specify the full path name in which the agent is saved.

    • crawl_includePaths — Optionally specify the directories from the catalog from which data is loaded. Delimit directories with a semicolon (;). This value overrides the value of the IncludePaths property in the BISearchConfig.properties file.

    • crawl_initalizeDataStore — Optionally specify whether to reinitialize the data store before doing a full crawl. This reinitializing retains the full-text catalog search configuration that is used with Oracle Endeca Server and removes all indexed data from the data store.

    • crawl_mdexDataStore — Optionally specify the name of the data store in Oracle Endeca Server that holds indexed records for the full-text catalog search. This value overrides the value of the MDEXDataStoreName property in the BISearchConfig.properties file.

    • crawl_startLocation — Optionally specify the node from which all data loading originates. This value overrides the value of the RootNode property in the BISearchConfig.properties file.

    For more information on the properties mentioned in this list, see Section 17.14.5, "Configuring Properties Manually for Searching."

  9. Click OK.

  10. Save the agent.

For complete information on creating agents, see "Creating Agents" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

17.13.5 Step 5: Configuring Properties for Full-Text Catalog Search Manually

You must manually configure properties for searching with Oracle Endeca Server, as described in Section 17.14.5, "Configuring Properties Manually for Searching."

17.13.6 Step 6: Editing the Configuration File to Enable Search

You must manually edit the configuration file for Oracle BI EE (called instanceconfig.xml) to include the appropriate elements, as described in Section 17.14.4, "Editing the Configuration File for Searching."

17.13.7 Step 7: Enabling SSL for the Full-Text Catalog Search

To use Oracle Endeca Server as the search engine for full-text searching, Oracle Business Intelligence must communicate with Oracle Endeca Server over the Secure Socket Layer (SSL). This type of communication requires SSL mutual authentication. Such authentication ensures that only methods from Oracle Business Intelligence can communicate with Oracle Endeca Server to load data and search the Oracle BI Presentation Catalog.

To enable Secure Socket Layer (SSL) to be used with the full-text catalog search:

  1. Enable SSL for Oracle Business Intelligence, as described in "Configuring SSL Communication Between Components" in Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition.

  2. Enable SSL in Oracle Endeca Server, as described in "Configuring the Dgraph for SSL Mutual Authentication" in Oracle Endeca Server Administrator's Guide at the following location:

    http://docs.oracle.com/cd/E35822_01/server.740/es_admin/toc.htm

  3. In the BISearchConfig.properties file, set the MDEXServer property to have a value that uses "https://" rather than "http://".

    For more information, see Section 17.14.5, "Configuring Properties Manually for Searching."

  4. Restart the BISearch application using Fusion Middleware Control.

17.13.8 Step 8: Enabling Users to Access the Full-Text Catalog Search

To enable users access to the full-text catalog search, ensure that the following are true:

17.14 Common Steps for Configuring Full-Text Search

Note:

Before reading this section, ensure that you familiar with Section 17.11, "Overview of Configuring for Full-Text Catalog Search."

Section 17.12 and Section 17.13 provide details on configuring for searching the Oracle BI Presentation Catalog with Oracle SES and with Oracle Endeca Server. While most of the configuration tasks are unique to each search engine, some details are shared. The following sections include the shared details. Do not perform these tasks until you review the complete procedures for configuring for full-text searching with each search engine.

17.14.1 Assigning Privileges for Searching

As part of the configuration process, you must assign privileges for searching.

To assign the appropriate privileges for searching the catalog:

  1. In Oracle BI Enterprise Edition, log in as an administrator.

  2. Click Administration in the global header.

  3. On the Administration tab, click Manage Privileges.

  4. In the SOAP section, ensure that the BISystem role has been granted the following privileges:

    Access SOAP
    Impersonate as system user
    Access "ReplicationService" Service
    Access "CatalogIndexingService" Service
    Access "SecurityService" Service
    Access "CatalogService" Service
    Access "XmlGenerationService" Service

For information about assigning privileges, see "Managing Presentation Services Privileges" in Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition.

17.14.2 Understanding Crawling and Data Loading

As part of the process of configuring for full-text catalog searching, you must understand the two types of crawls or data-loads that are required. The term "crawl" is used with Oracle SES and "data load" is used with Oracle Endeca Server.

  • Full crawl or data load — Crawls or data loads the entire catalog. Use this type the first time that a catalog is crawled or data loaded, or when a large number of changes have occurred since the previous crawl or data load. You generally schedule a full crawl or data load when most users are not accessing the system, such as over the weekend or a holiday. You must perform a full crawl or data load with replication enabled on a catalog before you can perform an incremental crawl or data load. See Section 17.12.6, "Step 6: Enabling Incremental Crawls for Full-Text Catalog Search" for information on enabling replication.

  • Incremental crawl or data load — Crawls, data loads, or actually indexes only those objects in the catalog that have changed. A changed object is one that has been created, edited, or deleted. An incremental crawl or data load does still access and build the entire catalog tree structure, but only the changed files are re-indexed. This provides a quick way to update the search index without re-indexing the entire catalog tree.

    Incremental crawls or data loads occur only if you enable replication and perform a full crawl or data load, as described in Section 17.14.3, "Enabling Incremental Crawls or Data Loads."

After the catalog is crawled or data loaded fully or incrementally, the objects are indexed so that users can easily search for them as part of the full-text catalog search.

By default, all objects in the catalog are set to be indexed during a crawl or data load. Content designers can use the Properties dialog for an object to set the Do Not Index property of that object. Setting this property prohibits the object from being crawled or data load and indexed. For more information, see "Accessing Properties" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

17.14.3 Enabling Incremental Crawls or Data Loads

For incremental crawls or data loads to occur, you must first do the following:

  1. Enable the replication of the Oracle BI Presentation Catalog by editing the instanceconfig.xml file, as described in the following procedure.

  2. Perform a full crawl or data load on the catalog.

To enable replication, set the Replication element to true in the instanceconfig.xml file. The following procedure provides information about configuring to enable replication.

Before you begin this procedure, ensure that you are familiar with the information in Section 3.4, "Using a Text Editor to Update Configuration Settings."

To manually edit the setting for replication:

  1. Open the instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Locate the Catalog section, in which you must add the Replication element.

    The Replication element is set to false by default. If you do not set it to true, then only full crawls or data loads of the catalog occur, no matter how minor the changes to the catalog since the last full crawl or data load.

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

    <Catalog>
       <Replication>
          <Enabled>true</Enabled>
       </Replication>
    </Catalog>
    
  4. Save your changes and close the file.

  5. Restart Oracle Business Intelligence.

17.14.4 Editing the Configuration File for Searching

As part of the process of configuring for full-text search, you must edit the instanceconfig.xml file to include the appropriate elements, as described in the following procedure. Some elements are shared by Oracle SES and Oracle Endeca Server, and some are unique to each engine.

Before you begin this procedure, ensure that you are familiar with the information in Section 3.4, "Using a Text Editor to Update Configuration Settings."

To manually edit the configuration file for search:

  1. Open the instanceconfig.xml file for editing as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Locate the ServerInstance section in which you must add the elements that are described in Table 17-3.

    Table 17-3 describes the elements for configuring for both the Oracle SES and Oracle Endeca Server engines. Some properties are needed for either of the engines, and some properties are needed specifically for one engine only. As you configure for the full-text catalog search, use only those elements from Table 17-3 that apply to the engine that you are using.

    See Section 17.11.3, "What Search Engines Are Supported?" for information on the two engines.

  3. Include the elements and their ancestor elements as appropriate, as shown in the following example.

    <ServerInstance>
      <BISearch>
        <Enabled>true</Enabled>
        <BaseURL>http://mycomputer:1111</BaseURL>
        <ContextName>bisearch</ContextName>
        <TimeOutMilliSeconds>60000</TimeOutMilliSeconds>
        <SearchGroup>mygroup</SearchGroup>
        <UseFacetUI>true</UseFacetUI>
      </BISearch>
      <UI>
        <MaxSearchResultItemsToReturn>300</MaxSearchResultItemsToReturn>
        <UserPickerDialogMaxAccounts>300</UserPickerDialogMaxAccounts>
      </UI>
    </ServerInstance>
    
  4. Save your changes and close the file.

Table 17-3 Elements for Configuring Search

Element Description Engine Default Value

BaseURL

Specifies the basic URL for Oracle Business Intelligence in the form:

http://computer_name:port

If SSL is enabled, then you must specify a URL that uses "https".

Both

No default value

ContextName

Specifies the name of the context for the BI Search Application, which must always be "bisearch".

Both

bisearch

Enabled

Specifies whether the instance of Oracle Business Intelligence is enabled to be crawled by Oracle SES or data-loaded by Oracle Endeca Server.

Both

false

MaxSearchResultItemsToReturn

See Section B.1, "Making Advanced Configuration Changes for Presentation Services" for a description of this setting, which limits the number of search results that are obtained by the full-text catalog search. In the Global Settings, Search (Query Configuration) section of the Oracle SES administration tool, set the value for Maximum Number of Results to the same value.

Both

300

UserPickerDialogMaxAccounts

See Section B.1, "Making Advanced Configuration Changes for Presentation Services" for a description of this setting, which controls the number of Catalog items that are displayed in the left picker.

Both

300

SearchGroup

Specifies the name of the search group that you created in Oracle SES. See Section 17.12.9.1, "Configuring the BI Search Application for Full-Text Search."

While this value is not used by Oracle Endeca Server, you must include a valid name.

Oracle SES

No default value

TimeOutMilliSeconds

Specifies the maximum number of milliseconds before the search request times out. If Presentation Services does not receive a response from the BI Search Application within the specified number of milliseconds, then a time-out message is displayed. There is no minimum or maximum value.]]

Both

60000

UseFacetUI

Specifies whether to use the facet user interface, as described in "What Results Are Returned from a Full-Text Catalog Search?" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

This value is used only by Oracle Endeca Server. Set the value to false for Oracle SES.

Oracle Endeca Server

true


17.14.5 Configuring Properties Manually for Searching

You can configure properties for the full-text catalog search by manually editing the BISearchConfig.properties file. Because the properties for the full-text catalog search include specifications for the URLs of web services that are used in the full-text catalog search, you can set these properties, if URLs change.

Table 17-4 describes the configuration properties for the full-text catalog search for both the Oracle SES and Oracle Endeca Server engines. Some properties are needed for either of the engines, and some properties are needed specifically for one engine only. As you configure for the full-text catalog search, use only those options from Table 17-4 that apply to the engine that you are using. See Section 17.11.3, "What Search Engines Are Supported?" for information on the two engines.

Table 17-4 describes properties that are found in the BISearchConfig.properties file. The BISearchConfig.properties file is installed into the ORACLE_HOME\user_projects\domains\bifoundation_domain/config/fmwconfig/biinstances/coreapplication directory on the WebLogic Server for Oracle BI EE.

Note:

If SSL is enabled, then you must specify a URL that uses "https" for the following properties: BIServerURL, BISearchServerURL, ECSF_DataServiceURL, ECSF_RedirectServiceURL, and ECSF_SecurityServiceURL.

Table 17-4 Configuration Properties for the Full-Text Catalog Search

Name Description Engine Default Value

BIServerURL

Specifies the URL for the Oracle BI Server.

Both

No default value

BISearchServerURL

Specifies the URL for the servlet for the full-text catalog search.

Both

No default value

BIServerSSOURL

Specifies the SSO URL for the Oracle HTTP Server instance that is configured to handle URL requests for Oracle BI EE.

Both

No default value

CrawlingUserKey

Specifies the key for the credentials that are used to crawl the catalog.

Do not edit this value.

Oracle SES

No default value

ECSF_DataServiceURL

Specifies the URL for the full-text search within the Oracle BI EE instance, in a format such as:

http://$OBIEE_INSTANCE:$OBIEE_PORT/bisearch/crawler

where $OBIEE_INSTANCE is the name of the computer on which Oracle BI EE is installed and $OBIEE_PORT is the port number for the Oracle BI EE instance.

Oracle SES

No default value

ECSF_RedirectServiceURL

Specifies the same URL as for the ECSF_DataServiceURL property.

Oracle SES

No default value

ECSF_SecurityServiceURL

Specifies the URL for the security service for the full-text search within the Oracle BI EE instance, in a format such as:

http://$OBIEE_INSTANCE:$OBIEE_PORT/bisearch/crawler/SecurityService

Oracle SES

No default value

ExcludePaths

Specifies the list of directories from the catalog that are not crawled or data-loaded. Delimit directories with a semicolon (;).

Both

"/system/*;/shared/*"

IncludePaths

Specifies the list of directories from the catalog that are crawled or data-loaded. Delimit directories with a semicolon (;).

Both

"*"

MDEXBulkLoadPort

Specifies the port number for the BulkLoad port, which is used by the Bulk Load interface of the Oracle Endeca Server to load data into the server.

Oracle Endeca Server

No default value

MDEXDataStoreName

Specifies the name of the data store in Oracle Endeca Server that holds indexed records for the full-text catalog search. You must create this data store using the procedure in Section 17.13.3, "Step 3: Creating the Data Store for Full-Text Catalog Search."

Oracle Endeca Server

No default value

MDEXServer

Specifies the host name or IP address of the computer on which Oracle Endeca Server is running with the appropriate protocol. For example, for regular http, specify the following:

http://localhost.com

If SSL is enabled, then specify the following:

https://localhost.com

Oracle Endeca Server

No default value

MDEXTransactionMaxSize

Specifies the number of indexed records that are included in each transaction during a crawl. This property enables you to control how often a transaction of indexed records is sent to Oracle Endeca Server.

Oracle Endeca Server

25

MDEXWSPort

Specifies the port number of the internal web services for Oracle Endeca Server.

Oracle Endeca Server

7770

MemoryThresholdValue

Specifies the threshold value of memory used to determine when a memory efficient method is used for large volumes of data.

Both

100

RootNode

Specifies the node from which all crawling originates.

Both

"/"

SearchEngine

Specifies the search engine to use. Valid values are SES (for Oracle SES) or MDEX (for Oracle Endeca Server).

Both

MDEX

SES_QueryProxyUserKey

Specifies the key for the user that serves as the query proxy user when using the web service for Oracle SES. You use this key when "Configuring the BI Search Application for Full-Text Search".

Oracle SES

No default value

SES_QueryServiceURL

Specifies the URL for the web service endpoint of the query in Oracle SES, in a format such as:

http://$SES_INSTANCE:$SES_PORT/search/query/OracleSearch

where $SES_INSTANCE is the name of the computer on which Oracle SES is installed and $SES_PORT is the port number for the Oracle SES instance.

Oracle SES

No default value


17.15 Replicating Oracle BI Presentation Catalogs

You can copy and merge the contents of selected catalog folders between instances of Presentation Services. You can split the replication configuration into individual tasks. The replication task is an instruction to periodically merge catalog contents for specified catalog folders from one server to another. Two-way replications are possible.

A typical scenario where replication is useful is when you use one instance of Presentation Services to prepare and publish shared analyses, and you use two or more production instances to support the users. In this scenario, you share the catalog from Instance 1 to two production instances and share the catalogs on each production instance with the other. To perform this sharing, you configure the following replication tasks in the configuration file for the Presentation Services Replication Agent:

When an instance of Presentation Services participates in replication, either as a publisher or as a subscriber, it tracks changes made to catalog objects that are marked to be replicated and keeps them internally in replication log files. Another instance of Presentation Services can make a SOAP call to request to export those changes to a file or to import and replay modifications recorded in a file exported earlier from another instance. The Presentation Services Replication Agent uses SOAP to manage replication-related activities on all instances of Presentation Services and performs import and export operations. For information about these SOAP calls, see Oracle Fusion Middleware Integrator's Guide for Oracle Business Intelligence Enterprise Edition.

17.15.1 About Replication Log Files

Replication log files record modifications made to catalog objects that are subject to replication. There are two types of replication log files:

  • Change log files — Contain records of modifications to catalog objects that were made locally. These files are stored in presentationcatalogpath/replication/changelog folder, where presentationcatalogpath is the full path to the catalog folder.

  • Playback log files — Contain records of modifications to catalog objects that were replayed from other instances of Presentation Services. These files are stored in presentationcatalogpath/replication/playback folder.

Replication log files are stored on disk indefinitely, until you periodically remove them. When performing replication operations, Presentation Services reads only replication log files from the time interval that is specified by the ReadLogRecordsSinceHoursAgo element in the instanceconfig.xml file. For information about this element, see Section 17.15.6, "Editing the instanceconfig.xml File for Replication."

While you might want to review replication log files, for example, for troubleshooting purposes, never edit log files manually.

17.15.1.1 Replication Log File Records

A replication log file contains different types of records, with each record consisting of several fields that are separated by commas. The most important types of records in a replication log file are described in Table 17-5.

Table 17-5 Description of Records in Replication Log Files

Type Written Contents

File header record

At the beginning of each log file

Size, Type, Timestamp, Version, Flags

Startup record

Each time Presentation Services starts

Size, Type, Timestamp

Before change record

When an Oracle BI Presentation Catalog object is about to be changed

Size, Type, Timestamp, Change sequence number, Change type

After change record

Immediately after a catalog operation has been completed

Size, Type, Timestamp, Change sequence number, Operation outcome

File finished record

As the last record in a replication log file

Size, Type, Timestamp, Name of next log file


The following list describes some fields in a replication log file:

  • Size. The size of the record in bytes and encoded as a hexadecimal number.

  • Type. The type of record, such as the following:

    • H. File header record

    • S. Presentation Services startup record

    • B. Before change record

    • A. After change Record

    • F. File finished record

  • Timestamp. The timestamp of the record, written as a hexadecimal number that represents the number of seconds from midnight (00:00:00), January 1, 1970 UTC.

  • Change sequence number. A sequence number that should be the same in the corresponding Before change and After change records.

  • Change type. The type of change, written as a hexadecimal number that represents a combination of the following flags:

    • 1. Insert

    • 2. Delete

    • 4. Write

    • 8. Change catalog object information

    • 16. Change owner

    • 32. Change security

  • Operation outcome. The operation result, which is one of the following:

    • 0. Fail

    • 1. Success

17.15.2 Configuring to Replicate an Oracle BI Presentation Catalog

To enable replication of an Oracle BI Presentation Catalog, perform the steps that are described in the following sections:

17.15.3 Copying Oracle BI Presentation Catalog Files

The Presentation Services Replication Agent copies changes made to an Oracle BI Presentation Catalog. Because it copies only changes and not the entire contents, you must first make a copy of the source catalog on each of the subscribing instances of Presentation Services.

17.15.4 Using the Oracle BI Presentation Services Replication Agent

You can run the Replication Agent on any computer that has network access to both instances of Presentation Services. This agent handles all the replication tasks and provides command-line options.

The Replication Agent (whose file name is sawrepaj) is a utility that performs common replication tasks such as copying, exporting, importing, and marking for replication.

The Replication Agent requires information about the instances of Presentation Services and the replication tasks. This information is stored in the config.xml file, and described in Section 17.15.5, "Creating the config.xml File for Replication."

The command line for the Replication Agent uses the following format:

  • In UNIX:

    sawrepaj.sh [/C path] command [command parameters]
    

    The sawrepaj.sh file is located in
    ORACLE_HOME\bifoundation\web\bin\sawrepaj.

  • In Windows

    sawrepaj.bat [/C path] command [command parameters]
    

    The sawrepaj.bat file is located in
    ORACLE_HOME\bifoundation\web\bin\sawrepaj.

The path following the "/C" specifies the path to the config.xml file. The "command" options are described in the following sections:

17.15.4.1 mark

Adds or removes the specified catalog folders from the list of catalog folders that are to be replicated on all or the specified computers that run Presentation Services. The list of catalog folders to be replicated is stored in a configuration item that is located in the presentationcatalogpath/root/system/replication directory, where presentationcatalogpath is the full path to the Oracle BI Presentation Catalog directory.

Adding a catalog folder to the list does not mean that the corresponding catalog object is immediately replicated. Only future modifications are noted in the replication log file and subsequently replicated.

When you replicate and the Oracle BI Presentation Catalog exists on another instance, the list of catalog folders to be replicated might be incorrect. Use the mark command to maintain the list of catalog folders to be replicated.

The syntax for the mark command is:

sawrepaj [/C path] mark {all|servername} [/n] [catalogfolders]
  • all | servername. The name of the computer that is running Presentation Services or "all," on which to run the mark command. If you use a specific server, then the name that you specify must match the name attribute of the corresponding server element in the config.xml file.

  • /n. If present, indicates that the catalog folder should be removed from the list of catalog folders to be replicated. Otherwise, the folder is added.

  • catalogfolders. A list of catalog folders to add or remove from the list of catalog folders to be replicated. Separate each folder name in the list with a space. To add or remove the entire Oracle BI Presentation Catalog (including all folders and such information as system privileges, Catalog Group membership, and so on), use /.

    If you do not specify any folders, then the mark command is executed on every folder for the servers that are specified in the config.xml file.

The following line shows a sample command for mark:

sawrepaj /C MyOracleHome\bifoundation\web\bin\sawrepaj mark all /

17.15.4.2 remotecopy

Exports the contents of the specified catalog folders from the source computer and imports them into the folders on the destination computer.

The syntax for the remotecopy command is:

sawrepaj [/C path] remotecopy sourceServer destinationServer catalogfolders
  • sourceServer. The name of the source computer as specified in the config.xml file.

  • destinationServer. The name of the destination computer as specified in the config.xml file.

  • catalogfolders. A list of catalog folders to copy remotely. Separate each folder name in the list with a space. If you do not specify any folders, then the remotecopy command is executed on every folder for the servers that are specified in the config.xml file.

The following line shows a sample command for remotecopy:

sawrepaj /C MyOracleHome\bifoundation\web\bin\sawrepaj remotecopy Server1 Server2 users shared

17.15.4.3 run

Executes all replication tasks that are specified in config.xml file and that have not expired. This command has no runtime parameters.

The syntax for the run command is:

sawrepaj [/C path] run

The following line shows a sample command for run:

sawrepaj /C MyOracleHome\bifoundation\web\bin\sawrepaj run

17.15.5 Creating the config.xml File for Replication

You must create the Replication Agent's configuration file to specify which folders on which instances of Presentation Services are to be replicated. The config.xml file is located in the ORACLE_HOME\bifoundation\web\bin\sawrepaj directory.

The following sections describe the config.xml file:

For information about manual editing, see Section 3.4, "Using a Text Editor to Update Configuration Settings."

17.15.5.1 Structure of the Configuration File

The structure of the Replication Agent's config.xml file is as follows:

<Config>
   <General>
      <ExportDirectory/>
      <LogExpiresHours/>
      <RetryAttempts/>
   </General>
   <Server>
      <Property/>
   </Server>
   <Folderset>
      <Folder/>
   </Folderset>
   <ReplicationTask/>
</Config>

17.15.5.2 Elements of the Configuration File

Table 17-6 describes the elements that you can set in the Replication Agent's config.xml file. You must enter the elements manually as they do not exist by default.

Table 17-6 Replication Agent Configuration Elements in config.xml

Element Description

Config

Serves as the root element for the configuration file.

Config/General

Contains general settings that are applicable to all instances and replication tasks.

General/ExportDirectory

Contains the UNC path to the shared directory where export files are placed. Must be accessible by the same name from all instances of Presentation Services.

In addition, the user account under which an instance of Presentation Services is running must have read/write permissions to this directory.

General/LogExpiresHours

Specifies the time in hours (as a double value) that replication logs expire on all instances of Presentation Services.

Set this element to the value of the ReadLogRecordsSinceHoursAgo element that is the lowest among all instances of Presentation Services that are participating in replication.

For information about the ReadLogRecordsSinceHoursAgo element, see Section 17.15.6, "Editing the instanceconfig.xml File for Replication."

General/RetryAttempts

Specifies the number of times an attempt to change an object is to be retried.

(An attempt to change an object might be retried, for example, if an object was locked.)

Config/Server

Defines connection information for each computer for Presentation Services. Its attributes are:

  • name. The logical ID of the server, which is used to identify it in replication tasks and in the sawrepaj command line.

  • user. The user name.

  • pwd. The password.

Config/Server/Property

Defines connection parameters for the Presentation Services (SAWBridge) server and the transport protocol. Its attributes are:

Defines server name and value:

Note: The settings that you use here are determined by whether the value for the transport protocol is set to use HTTP (N) or socket based TCP (Y).

  • name - Defines the server name, for example:

    oracle.bi.presentation.url - (when using HTTP protocol)

    oracle.bi.presentation.sawservers - (when using socket based TCP protocol).

  • value - Defines the server address, for example:

    http://localhost/analytics/saw.dll - (when using HTTP protocol) the mapping alias of SAWBridge servlet

    localhost:9710 - (when using socket based TCP protocol).

Defines the transport protocol name and value:

  • name - The transport protocol name, for example:

    oracle.bi.presentation.usesoaptcptransport

  • value - The transport protocol for connecting to the Presentation Services can be either of the following:

    N - Use HTTP protocol (Default value).

    Y - Use socket based TCP protocol.

Config/Folderset

Defines a list of catalog folders. Its only attribute is name, which you can set to the logical ID of the server or to "all".

Folderset/Folder

Adds a folder to the folderset. Specifies the full path to the catalog folder.

Config/ReplicationTask

Defines the replication tasks. Its attributes are:

  • source. The name of the source computer. This must match the name of an instance that is defined in the Server element.

  • destination. The name of the destination computer. This must match the name of an instance that is defined in the Server element.

  • folders. The name of the folderset. This must match a folderset that is defined in a Folderset element.

  • lastPerformed. The timestamp of the last successful run of this task. The sawrepaj utility updates this value.

  • localChanges. Specifies whether changes made directly on the source computer are to be exported:

    true. Changes are to be exported. (Default)

    false. Changes are not to be exported.

  • remoteChanges. Specifies whether changes that were made on another server and that were replicated on the source server are to be reexported:

    true. Changes are to be re-exported.

    false. Changes are not to be re-exported. (Default)


17.15.5.3 Example config.xml File

The following is an example of the config.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Oracle BI Presentation Services Replication Agent Configuration File -->
<!-- replicate entire catalog from host1 to host2 -->

<Config>
      <General>
         <ExportDirectory>\\host1\shared</ExportDirectory>
         <LogExpiresHours>48</LogExpiresHours>
      </General>
      <Server name="1" user="<admin1user>" pwd="<admin1password>">
        <Property name= "oracle.bi.presentation.url"
        value ="http://host1.com:<port>/analytics/saw.dll"/>
        <Property name="oracle.bi.presentation.usesoaptcptransport" value="N"/>
      </Server>
      
      <Server name="2" user="admin2user" pwd="admin2password">
      <Property name="oracle.bi.presentation.sawservers"
        value ="localhost:10712"/>
      <Property name="oracle.bi.presentation.usesoaptcptransport" value="Y"/>
      </Server>

      <Folderset name="all">
         <Folder>/</Folder>
      </Folderset>

      <ReplicationTask destination="2" source="1" folders="all" />
   </Config>

17.15.6 Editing the instanceconfig.xml File for Replication

For each instance of Presentation Services that contains a catalog to replicate, you must edit the instanceconfig.xml file for the following:

  • Enable replication. By default, the replication functionality is disabled for instances of Presentation Services.

  • Configure replication for a clustered environment. In a clustered environment, several instances of Presentation Services can share the same Oracle BI Presentation Catalog. For replication to work properly, you must:

    • Ensure that each instance of Presentation Services writes to its own log file to avoid concurrency issues.

    • Ensure that changes made by all instances are taken into account during import and export operations.

  • Specify the number of records to be kept in a replication log file.

  • Specify the time period (in hours) from which replication log files are to be read for replication operations.

The following procedure provides information about configuration changes that you can make for replication. Before you begin this procedure, ensure that you are familiar with the information in Section 3.4, "Using a Text Editor to Update Configuration Settings."

To manually edit the settings for the replication of catalogs:

  1. Open the instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Locate the section in which you must add the elements that are described in Table 17-7.

  3. Include the elements and their ancestor elements as appropriate, as shown in Example 17-1.

    Note:

    Do not insert multiple Catalog elements into a single instanceconfig.xml file. Search for an existing Catalog element and if it exists, use that element for holding the elements that are shown in this example.

  4. Save your changes and close the file.

  5. Restart Presentation Services.

Table 17-7 Elements for Configuring Catalog Replication

Element Description Default Value

Enabled

Specifies whether the instance of Presentation Services is to participate in replication, as either a publisher or subscriber.

false

ReadLogRecordsSinceHoursAgo

Specifies the time period (in hours) from which replication log files are to be read for replication operations.

168

RecordsInFileLimit

Specifies the number of records to be kept in a replication log file.

5000

IDsInCluster

Identifies, by ID, all instances of Presentation Services that are in the cluster. Separate each ID by a comma.

This element is required in a clustered environment.

No default value

MyInstanceID

Identifies which of the IDs that were specified in the IDsInCluster element to use as the suffix for log files that are generated by this instance of Presentation Services. Log files are named as follows:

  • For change log files:

    sawchange_InstanceID_SequenceNum.log

  • For playback log files:

    sawplayback_InstanceID_SequenceNum.log

See Table 17-8 for example file names.

This element is required in a clustered environment.

No default value


Example 17-1 instanceconfig.xml Files on Multiple Servers for Replication

Suppose that you have two servers for which you want to enable replication. You set the instanceconfig.xml file to the following values on Server1:

<ServerInstance>
<Catalog>
  <Replication>
    <Enabled>true</Enabled>
    <ReadLogRecordsSinceHoursAgo>120</ReadLogRecordsSinceHoursAgo>
    <RecordsInFileLimit>4000</RecordsInFileLimit>
    <Cluster>
      <IDsinCluster>ID_FOR_S1, ID_FOR_S2</IDsinCluster>
      <MyInstanceID>ID_FOR_S1</MyInstanceID>
    </Cluster>
  </Replication>
</Catalog>
</ServerInstance>

On Server2, you set the instanceconfig.xml file to these same values, with one exception. You set the MyInstanceID element to a value of ID_FOR_S2 to indicate that log files that are generated by the instance of Presentation Services on this server use a suffix of ID_FOR_S2.

<MyInstanceID>ID_FOR_S2</MyInstanceID>

Table 17-8 shows sample replication log files names that are generated by Server1 and Server2. Each node in the cluster must know the names of the other server log files to read replication information that is generated by the other servers.

Table 17-8 Replication Log File Names by Server

Log File Type Server1 Server2

Change log

sawchange_ID_FOR_S1_1.log

sawchange_ID_FOR_S1_2.log

sawchange_ID_FOR_S1_3.log

sawchange_ID_FOR_S1_4.log

sawchange_ID_FOR_S2_1.log

sawchange_ID_FOR_S2_2.log

sawchange_ID_FOR_S2_3.log

sawchange_ID_FOR_S2_4.log

Playback log

sawplayback_ID_FOR_S1_1.log

sawplayback_ID_FOR_S1_2.log

sawplayback_ID_FOR_S1_3.log

sawplayback_ID_FOR_S1_4.log

sawplayback_ID_FOR_S2_1.log

sawplayback_ID_FOR_S2_2.log

sawplayback_ID_FOR_S2_3.log

sawplayback_ID_FOR_S2_4.log


17.15.7 Resuming Replication if Replication Log Files Are Unavailable

If, for some reason, replication log files are unavailable in an instance of Presentation Services, then you can resume replication by copying over the Oracle BI Presentation Catalog folders that the instance subscribes to. However, this method loses the catalog contents that were not replicated to other instances. The following method preserves all catalog contents.

Note:

If you must resume replication after Presentation Services has been offline for a time period in excess of that specified in the ReadLogRecordsSinceHoursAgo element in the instanceconfig.xml file, then you can adjust the value of ReadLogRecordsSinceHoursAgo so that log files in the offline period are replicated. Then, reset ReadLogRecordsSinceHoursAgo back to its original setting.

To resume replication if replication log files are unavailable:

  1. Use Catalog Manager to erase all replication logs in the presentationcatalogpath/replication/changelog and presentationcatalogpath/replication/playback folders, where presentationcatalogpath is the full path to the Oracle BI Presentation Catalog folder.

    For information about Catalog Manager, see Chapter 11, "Configuring Connections to External Systems."

  2. Set the UseReplication element in the instanceconfig.xml file to false.

    For information, see Section 17.15.6, "Editing the instanceconfig.xml File for Replication."

  3. Start the instance of Presentation Services.

  4. Delete or rename folders that are replicated from other instances and copy them over from other instances using the sawrepaj remotecopy command.

  5. Set the UseReplication element in instanceconfig.xml to true.

  6. Restart the instance of Presentation Services.

  7. Restore the list of folders to be replicated using the sawrepaj mark command on the instance of Presentation Services.

  8. Reenable replication tasks by editing the configuration file to delete the lastPerformed attribute from all ReplicationTask elements that have the instance of Presentation Services as an import or export target.