B Exception Handling

This appendix provides procedures to handle exceptions during or after migrating from Oracle BI 11g to 12c.

  • Configuration Failure with TRANSFORMBAREXCEPTION
    The 12c configuration might fail with a TRANSFORMBAREEXCEPTION error, if any objects in the catalog are older than Release 11.1.1.7. You can confirm the need to update the catalog items by viewing the metrics in Fusion Middleware Control. In the Catalog folder, find a metric called Reads Needing Upgrade with the 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.
  • Multiple Y-Axis Highcharts Graph is not Displayed After Migration
    You may not be able to render the Multiple Y-axis Highcharts graph in 12c after migration because the required JavaScript (.js) files are not present in the 12c instance.
  • Setting the Evaluate Parameter in the NQSConfig.INI File
    The EVALUATE function in your analyses is not enabled by default in Logical SQL queries because it exposes the database to SQL injection attacks. If you encounter any error while generating any views after migrating to Oracle BI 12c, then you must set the value of the EVALUATE_SUPPORT_LEVEL parameter appropriately in the NQSConfig.INI file.
  • Error: ava.lang.NoClassDefFoundError: Could not initialize class sun.awt.X11GraphicsEnvironment
    You can encounter the "ava.lang.NoClassDefFoundError: Could not initialize class sun.awt.X11GraphicsEnvironment" error if you have set the value of the DISPLAY variable manually or the system has manipulated it automatically. In case you change the value of the DISPLAY variable to a Windows-client system IP, to run the 64-bit Linux installer through a Windows client, reset it to its original value after the installation is complete. If you generate an analysis that contains graphs without resetting the value of the DISPLAY variable, you can get this error.
  • Verifying File Data Sources in Oracle BI Publisher
    While generating reports, if you encounter an error stating oracle.xdo.XDOException: File does not exist or is not readable:..., you might not have copied the supporting XML files to the 12c system. To solve this issue, manually validate that the path for each data source points to the appropriate directory on the 12c system.
  • [nQSError: 46168] Operation RawFile::checkSoftLimit failed
    You can get the [nQSError: 43119] Query Failed: [nQSError: 46168] Operation RawFile::checkSoftLimit failed, it'll exceed the current limitation. 1073758528 error if the BI query requires more temporary space to complete the request than the BI Administrator has allocated.
  • Act As Configuration Failing in 12c
    The Act As functionality allows you to act for another user in Oracle BI EE. This functionality is useful, for example, when you need to work on another user's dashboard or content, or when IT support staff wants to troubleshoot another user's account. If you have migrated from BI 11g to 12c, and are unable to configure Act As functionality in 12c, follow the procedure in this topic to fix the issue.
  • Custom Link and SampleApp Oracle Technology Network Page Not Visible Post Migration
    Custom Link and SampleApp Oracle Technology Network page may not be visible in the 12c system directly after the migration. This happens because the Custom Links xml settings is not copied from BI 11g to 12c during the migration. You must manually copy the Custom Links xml settings from BI 11g to 12c.
  • Migrating 11g WebLogic Users to 12c
    After migrating from 11g to 12c, you must manually migrate the WebLogic users in to your 12c domain. You can do this by exporting the security data from a security realm and importing it in to another security realm. Security data includes authentication, authorization, credential map, and role data.

B.1 Configuration Failure with TRANSFORMBAREXCEPTION

The 12c configuration might fail with a TRANSFORMBAREEXCEPTION error, if any objects in the catalog are older than Release 11.1.1.7. You can confirm the need to update the catalog items by viewing the metrics in Fusion Middleware Control. In the Catalog folder, find a metric called Reads Needing Upgrade with the 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.

To update the catalog:
  1. Sign in to Oracle BI EE with administration credentials.
  2. In the global header, click Administration.
  3. Click the Scan and Update Catalog Objects That Require Updates link.
  4. 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.
Restart Oracle BI Presentation Services using Enterprise Manager Fusion Middleware Control.
  • Regenerating User GUIDs
    This task requires that you manually edit the configuration files to instruct Oracle BI Server and Oracle BI Presentation Server to regenerate the GUIDs on restart. Once completed, you edit these files again to remove the modification.
  • Updating Oracle Business Intelligence Catalogs
    When migrating from 11g, you must manually update your Oracle BI Presentation Services Catalog.

B.1.1 Regenerating User GUIDs

This task requires that you manually edit the configuration files to instruct Oracle BI Server and Oracle BI Presentation Server to regenerate the GUIDs on restart. Once completed, you edit these files again to remove the modification.

For information about where to locate Oracle Business Intelligence configuration files, see Configuration Files in Oracle Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition.
To regenerate user GUIDs:
  1. Update the FMW_UPDATE_ROLE_AND_USER_REF_GUIDS parameter in the 11g NQSConfig.INI file.
    1. Open the 11g NQSConfig.INI file for editing. ThE NQSConfig.INI file is located at the following location:
      On UNIX operating system:
      DOMAIN_HOME/config/OracleBIServerComponent/coreapplication_obisn
      On Windows operating system:
      DOMAIN_HOME\config\OracleBIServerComponent\coreapplication_obisn
    2. Locate the FMW_UPDATE_ROLE_AND_USER_REF_GUIDS parameter and set it to YES, as follows
      FMW_UPDATE_ROLE_AND_USER_REF_GUIDS = YES;
    3. Save and close the file.
  2. Update the Catalog element in the 11g instanceconfig.xml file. The instanceconfig.xml file is located at the following location:
    On UNIX operating system:
    DOMAIN_HOME/config/OracleBIPresentationServicesComponent/coreapplication_obipsn
    On Windows operating system:
    DOMAIN_HOME\config\OracleBIPresentationServicesComponent\coreapplication_obipsn
    1. Open instanceconfig.xml for editing:
    2. Locate the Catalog element and update it as follows: 
      <Catalog>
<UpgradeAndExit>false</UpgradeAndExit>
<UpdateAccountGUIDs>UpdateAndExit</UpdateAccountGUIDs>
</Catalog>
    3. Save and close the file.
  3. Restart the Oracle BI system components using opmnctl: 
    cd ORACLE_HOME/admin/instancen/bin
./opmnctl stopall
./opmnctl startall
  4. Set the FMW_UPDATE_ROLE_AND_USER_REF_GUIDS parameter in the NQSConfig.INI file back to NO.

    Important:

    You must perform this step to ensure that your system is secure.
  5. Update the Catalog element in the 11g instanceconfig.xml file to remove the UpdateAccount GUIDs entry.
  6. Restart the Oracle BI system components using opmnctl: 
    cd ORACLE_HOME/admin/instancen/bin
./opmnctl stopall
./opmnctl startall

B.1.2 Updating Oracle Business Intelligence Catalogs

When migrating from 11g, you must manually update your Oracle BI Presentation Services Catalog.

To update the Oracle BI catalog:
  1. Shut down Oracle BI Presentation Services using the Fusion Middleware Control.
    For more information, see Using Fusion Middleware Control to Start and Stop BI System Component Processes in Oracle Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition.
  2. Back up your Release 10g catalogs by using the 7-Zip utility to create a compressed file.
  3. Create a backup copy of the instanceconfig.xml file. The instanceconfig.xml file is located at the following location:
    On UNIX operating system:
    DOMAIN_HOME/config/OracleBIPresentationServicesComponent/coreapplication_obipsn
    On Windows operating system:
    DOMAIN_HOME\config\OracleBIPresentationServicesComponent\coreapplication_obipsn
  4. Change the UpgradeAndExit option to true in the instanceconfig.xml file.
    Find the following code: 
    <ps:Catalog xmlns:ps="oracle.bi.presentation.services/config/v1.1">
   <ps:UpgradeAndExit>false</ps:UpgradeAndExit>
</ps:Catalog>

    Change it to the following:

    <ps:Catalog xmlns:ps="oracle.bi.presentation.services/config/v1.1">
   <ps:UpgradeAndExit>true</ps:UpgradeAndExit>
</ps:Catalog>
  5. Start Oracle BI Presentation Services using the following OPMN command to update the catalogs:
    opmnctl startproc ias-component=coreapplication_obipsn
    Where, n is the instance.
    For example:
    On UNIX operating system:
    cd ORACLE_INSTANCE/bin
    ./opmnctl startproc ias-component=coreapplication_obips1
    On Windows operating system:
    cd ORACLE_INSTANCE\bin
    opmnctl startproc ias-component=coreapplication_obips1
  6. After the catalogs are updated, edit the instanceconfig.xml file again and change the UpgradeAndExit option back to false.
  7. Restart Oracle BI Presentation Services using the Fusion Middleware Control.

B.2 Multiple Y-Axis Highcharts Graph is not Displayed After Migration

You may not be able to render the Multiple Y-axis Highcharts graph in 12c after migration because the required JavaScript (.js) files are not present in the 12c instance.

To copy the files to the 12c system:
  1. Go to the \AnalyticsRes directory on the 11g system.
  2. Copy the following files from the 11g \AnalyticsRes directory to the 12c \AnalyticsRes directory:
    • highcharts.js
    • exporting.js
    • jquery-1.8.2.min.js

B.3 Setting the Evaluate Parameter in the NQSConfig.INI File

The EVALUATE function in your analyses is not enabled by default in Logical SQL queries because it exposes the database to SQL injection attacks. If you encounter any error while generating any views after migrating to Oracle BI 12c, then you must set the value of the EVALUATE_SUPPORT_LEVEL parameter appropriately in the NQSConfig.INI file.

The default value of the EVALUATE_SUPPORT_LEVEL parameter is "0", which means that evaluate is not supported.

# EVALUATE_SUPPORT_LEVEL:
# 1: evaluate is supported for users with manageRepositories permission
# 2: evaluate is supported for any user.
# other: evaluate is not supported if the value is anything else.
EVALUATE_SUPPORT_LEVEL = 0;

Manually set the value of the EVALUATE_SUPPORT_LEVEL parameter same as it is in the 11g NQSConfig.INI file or as required by your organization.

The NQSConfig.INI file is located at the following location:

On UNIX operating system:
DOMAIN_HOME/config/fmwconfig/biconfig/OBISn
On Windows operating system:
DOMAIN_HOME\config\fmwconfig\biconfig\OBISn

B.4 Error: ava.lang.NoClassDefFoundError: Could not initialize class sun.awt.X11GraphicsEnvironment

You can encounter the "ava.lang.NoClassDefFoundError: Could not initialize class sun.awt.X11GraphicsEnvironment" error if you have set the value of the DISPLAY variable manually or the system has manipulated it automatically. In case you change the value of the DISPLAY variable to a Windows-client system IP, to run the 64-bit Linux installer through a Windows client, reset it to its original value after the installation is complete. If you generate an analysis that contains graphs without resetting the value of the DISPLAY variable, you can get this error.

To fix this error:
  1. Reset the value of the DISPLAY variable.
  2. Restart the JavaHost process.

B.5 Verifying File Data Sources in Oracle BI Publisher

While generating reports, if you encounter an error stating oracle.xdo.XDOException: File does not exist or is not readable:..., you might not have copied the supporting XML files to the 12c system. To solve this issue, manually validate that the path for each data source points to the appropriate directory on the 12c system.

To validate paths for the data source names:
  1. Sign in to Oracle BI Publisher.
  2. Go to File under Data Source on the Administration page.
    On the File page, you can see the directory path for each DSN.
  3. Check whether the file is pointing to the correct 12c directory.
  4. To change the directory path, click the DSN.
    You are navigated to the Update Data Source page.
  5. Enter the correct and the complete path of top-level directory and click Apply.

B.6 [nQSError: 46168] Operation RawFile::checkSoftLimit failed

You can get the [nQSError: 43119] Query Failed: [nQSError: 46168] Operation RawFile::checkSoftLimit failed, it'll exceed the current limitation. 1073758528 error if the BI query requires more temporary space to complete the request than the BI Administrator has allocated.

To resolve this issue:
  1. Modify the query to reduce the volume of data that is processed by the BI Server by:
    1. Adding additional filters to the query.
    2. Replacing the most detailed attribute columns with less detailed columns to reduce the overall level of detail of the query.
    3. Removing attribute columns containing long text values.
    4. Avoiding the use of SQL functions that are not supported by the backend data source.
    5. Removing certain attribute or measure columns that cause more complex internal processing in the BI Server.
  2. If you cannot resolve the issue by modifying or restructuring the query and if the system is capable of handling more load, request the BI Administrator to increase the maximum size allowed for temporary files by modifying the following parameters in the NQSConfig.INI file:
    • WORK_DIRECTORY_SIZE_GLOBAL_LIMIT or
    • MAX_WORK_FILE_SIZE_PERCENT
    For example:
    [General]
WORK_DIRECTORY_SIZE_GLOBAL_LIMIT = 100 GB;
# No temporary file will be allowed to exceed this percentage of the global work
# directory limit.
MAX_WORK_FILE_SIZE_PERCENT = 5;

    Note:

    • The maximum size allowed for any single temporary file is determined by multiplying the total size limit of the temporary directory set in the WORK_DIRECTORY_SIZE_GLOBAL_LIMIT parameter by the percentage specified in MAX_WORK_FILE_SIZE_PERCENT. By default the temporary file size limit is 100 GB * 5% = 5 GB. This per-file limit applies to each temporary file individually, while the total WORK_DIRECTORY_SIZE_GLOBAL_LIMIT applies collectively to all the temporary files created by the BI Server.

    • You must increase the MAX_WORK_FILE_SIZE_PERCENT parameter cautiously. Setting a large percentage can allow a single request to consume a large portion of the total temporary space, possibly causing the system and other BI requests to run out of temporary space and fail. Increasing the WORK_DIRECTORY_SIZE_GLOBAL_LIMIT is safer as long as there is sufficient disk space. However, you must observe caution while increasing the value of the WORK_DIRECTORY_SIZE_GLOBAL_LIMIT parameter. Setting a large value can cause the system to run out of disk space or allow BI requests to consume too many system resources.

B.7 Act As Configuration Failing in 12c

The Act As functionality allows you to act for another user in Oracle BI EE. This functionality is useful, for example, when you need to work on another user's dashboard or content, or when IT support staff wants to troubleshoot another user's account. If you have migrated from BI 11g to 12c, and are unable to configure Act As functionality in 12c, follow the procedure in this topic to fix the issue.

Before configuring Act As functionality in 12c:
  1. Create the "customMessages" folder under the following directory:
    On UNIX operating system:
    ORACLE_HOME/bi/bifoundation/web/msgdb/l_en
    On Windows operating system:
    ORACLE_HOME\bi\bifoundation\web\msgdb\l_en
  2. Copy the 11g LogonParamSQLTemplate.xml file to the "customMessages" folder created in step 1.
For more information about creating a custom message template, see Creating a Custom Message Template for Proxy Functionality.

B.8 Custom Link and SampleApp Oracle Technology Network Page Not Visible Post Migration

Custom Link and SampleApp Oracle Technology Network page may not be visible in the 12c system directly after the migration. This happens because the Custom Links xml settings is not copied from BI 11g to 12c during the migration. You must manually copy the Custom Links xml settings from BI 11g to 12c.

To copy the Custom Links xml settings:
  1. Copy the Custom Links xml to the following folder on your 12c system:
    On UNIX operating system:
     DOMAIN_HOME/bidata/components/OBIPS(customMessages)
    On Windows operating system:
     DOMAIN_HOME\bidata\components\OBIPS(customMessages)
  2. Open the Oracle BI EE instanceconfig.xml for editing and find the <CustomLinks> directive.
  3. Enable the custom links as shown in the following example: 
    <CustomLinks>
<Enabled>true</Enabled>
</CustomLinks>

B.9 Migrating 11g WebLogic Users to 12c

After migrating from 11g to 12c, you must manually migrate the WebLogic users in to your 12c domain. You can do this by exporting the security data from a security realm and importing it in to another security realm. Security data includes authentication, authorization, credential map, and role data.

Understand when you would want to migrate security data. See Overview of Security Data Migration.

Understand the concepts associated with importing and exporting security data. See Migration Concepts.

Understand which formats and constraints are supported by the WebLogic Security providers. See Formats and Constraints Supported by WebLogic Security Providers.

Note:

You can only export and import security data between security realms in the same WebLogic Server release.

B.9.1 Exporting the security data from a security provider

To export security data from a security provider to a file:
  1. In the left pane, select Security Realms and then select the name of the realm you are configuring (for example, myrealm).
  2. Select the type of provider from which you want to export security data (for example, Authentication).
  3. Select the security provider from which you want to export security data.
  4. Select Export under Migration.
  5. Specify the directory and filename in which to export the security data in the Export File on Server field. The directory must exist.

    Note:

    The directory and file into which you export the security data should be carefully protected with operating system security as they contain secure information about your deployment.
  6. (Optional) Define a specific set of security data to be exported in the Export Constraints box.
  7. Click Save.
    After you export the data from the security provider, you can import it any time.

B.9.2 Importing the security data into a security provider

To import security data into a security provider:
  1. In the left pane of the Administration Console, select Security Realms.
  2. Select the name of the security realm into which the security data is to be imported (for example, myrealm).
  3. Select Providers and then the type of provider into which security data is to be imported (for example, Authentication under Providers).
  4. Select the security provider in which the security data is to be imported and select Import under Migration.
  5. Specify the directory and file name of the file that contains the exported security data in the Import File on Server field.
  6. Click Save.