Maintaining the Oracle BI Presentation Catalog

Refer to the topics below for information on maintaining a catalog.

Manually Changing Configuration Settings for the Catalog

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

Open the instanceconfig.xml file for editing located in:

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

Keep the following points in mind:
- Hashing is not typically needed for modern operating systems that use modern file systems (for example, ext4, ZFS, ntfs); however, it may still be useful for performance when your user base exceeds approximately 4,000 users.
- Oracle recommends that you hash a catalog at creation time; however, there are circumstance that require hashing the catalog after it is in use. Take a backup and run the following command for more information:
  
  On UNIX:
  
  runcat.sh -cmd rehash -help
  
  On Windows:
  
  runcat.cmd -cmd rehash -help
- In general, do not set the HashUserHomeDirectories element to a value greater than 2, because a higher setting negates the effectiveness of hashing.
- Include only one Catalog element in the instanceconfig.xml file or unexpected results might occur. Unless expressly noted, include most nodes in an XML document only once.

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

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

Save your changes and close the file.
Restart Presentation Services.

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:

Deploying Catalogs to Production

You deploy a Catalog to production using BAR files.

See Moving Oracle Business Intelligence Between Environments.

Deploying Objects to Production

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

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

Archive the catalog object in the test environment and unarchive it in the production environment as follows:
1. Archive the catalog object in the test environment using one of the following:
  - Oracle BI Presentation Services.
  - Catalog Manager.
    
    See Archiving and Unarchiving Using Catalog Manager.
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 Archiving and Unarchiving Using Catalog Manager.
4. Set the permissions on the object as appropriate.
(Optional) If you are deploying the catalog to an existing production environment.

Copy and paste new or updated objects from the test catalog into the production catalog as follows:
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.

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 are not upgraded properly. You can confirm the need to update by viewing the metrics in Fusion Middleware Control. In the Catalog folder, find a metric called "Reads Needing Upgrade" with description "The number of objects read that required upgrading." If the number is large, then you can resolve this issue by updating objects in the catalog using the Administration page in Presentation Services.

You upgrade to new versions of Oracle Business Intelligence by following the instructions in the Upgrade Guide for Oracle Business Intelligence. To upgrade Catalog objects follow Task 5: Upgrade the Oracle BI Repository and Catalog in Upgrade Guide for Oracle Business Intelligence. Oracle recommends that you upgrade when Presentation Services is not running. If you suspect that the upgrading of objects was not performed thoroughly during the upgrade process, then you can update the objects yourself using the Administration page. The advantage of this approach is that Presentation Services can stay up and running during the update.

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

If you are performing a rolling upgrade of machines in a cluster, then do not use this option or the UpgradeAndExit configuration setting until all machines in the cluster are upgraded.
Use this option on only one node in a cluster at a time.

In the global header, click Administration.
Click the Scan and Update Catalog Objects That Require Updates link.
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.

Validating the Catalog

The catalog is a dynamic component which requires maintenance.

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

This section contains the following topics about validating the catalog:

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.

Tasks in the Validation Process

You can validate the system to ensure processes run smoothly.

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.

Important Guidelines for Validating the Catalog

Before you validate the catalog, keep in mind certain guidelines.

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.

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.

Stop Presentation Services.

See Using Fusion Middleware Control to Start and Stop BI System Component Processes.
Back up the catalog by using the 7-Zip utility to create a compressed file for it.
Create a backup copy of the instanceconfig.xml file located in:

BI_DOMAIN/config/fmwconfig/biconfig/OBIPS
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.

See Specifying the Elements for Validating the Catalog.
Start Presentation Services to run the validation according to the values that you specified in the instanceconfig.xml file.
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.
Repeat Steps 5 through 7 until the catalog is validated.
Stop Presentation Services.
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.
Restore the backup version of the instanceconfig.xml that you created earlier to use as the current version.
Start Presentation Services.

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.

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

BI_DOMAIN/config/fmwconfig/biconfig/OBIPS

Locate the Catalog section in which you must add these elements.

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:

None — Specifies that no validation is performed.
Report — Specifies that details about each inconsistent object are written to the sawlog.log file.

See What Are Diagnostic Log Configuration Files and Where Are They Located?
Clean — Specifies that details about each inconsistent object are written to the sawlog.log file and that each object is removed from the catalog.

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.
Save your changes and close the file.