E Migrating Existing BI Beans Projects

This appendix provides instructions for migrating existing BI Beans projects from Oracle9i JDeveloper (9.0.4). If you must migrate projects from an earlier version of BI Beans 10.1.2, then consider performing the optional task that is described in Section E.5, "Post-Migration Task for the BI Beans Catalog (Optional)". This appendix includes the following topics:

• Section E.1, "Migrating the Oracle OLAP Instance (Optional)"

• Section E.2, "Migrating the BI Beans Catalog"

• Section E.3, "Migrating User Settings from Previous Releases"

• Section E.4, "Migrating the BI Beans Workspaces"

• Section E.5, "Post-Migration Task for the BI Beans Catalog (Optional)"

E.1 Migrating the Oracle OLAP Instance (Optional)

BI Beans 10.1.2 applications can run against Oracle9i Release 2 or Oracle Database 10g Release 1 or Release 2 Enterprise Edition. Before performing other migration steps, you must decide which database version to use, as described in the following list:

• If you want to upgrade BI Beans applications to run against Oracle9i Release 2 Enterprise Edition and the applications currently run against an earlier version of the database, then you must upgrade the database before migrating the applications. For information, see Oracle9i OLAP Release 2 - Installation Guide.

• If you want to upgrade BI Beans applications to run against Oracle Database 10g Release 1 Enterprise Edition, and the applications currently run against an earlier version of the database, then you must upgrade the database before migrating the applications. For complete migration information for Oracle OLAP, refer to the Oracle OLAP Application Developer's Guide for the Oracle Database 10g Release 1 Enterprise Edition.

See Section B.3.1, "Database Requirements for Oracle Business Intelligence Tools" for information on the supported database versions.

E.2 Migrating the BI Beans Catalog

To migrate a remote BI Beans Catalog, run the upgrade utility that is delivered with BI Beans. The utility is named bi_upgradecatalog.bat and is located in the JDEV_HOME\bibeans\bin director, where JDEV_HOME is the directory into which JDeveloper is installed:

Important: You can only use the utility to upgrade from BI Beans version 9.0.3 or version 9.0.4 to BI Beans version 10.1.2. Always run the utility that is delivered with the most recent version of BI Beans.

For complete information about the Catalog migration utility, see the Help topic that is called "BI Beans Catalog Upgrade Utility" in the BI Beans Help system.

E.2.1 Additional Step for Migration to Oracle Database 10g Enterprise Edition Release 2

In addition to running the upgrade utility to migrate an existing BI Beans Catalog to Oracle Database 10g Enterprise Edition Release 2 (10.2.0.1 and higher), you must also update a PL/SQL package on the database server by performing the following procedure:

1. Install the patch as follows:

   1. Locate the bidatasvr.jar in the BI Beans installation directory.

   2. Extract the bibcoreb.pls file from bidatasvr.jar to a local directory. The jar has packing scope and will be extracted into the oracle\dss\persistence\storagemanager\bi\scripts directory.

2. Apply the patch as follows:

   1. At the command prompt, enter:

      cd oracle\dss\persistence\storagemanager\bi\scripts

   2. Open a sqlplus session. For example, enter:

      sqlplus BIBCAT/BIBCAT@mydb

      where mydb is the connect string and BIBCAT/BIBCAT is the username/password of the owner of the schema that hosts the BI Beans Catalog.

   3. At the sqlplus prompt, enter:

      SQL> @bibcoreb.pls

      This step displays the following output:

      Package body created. 
      Commit complete.
      
      

3. Ensure that the package is valid as follows:

   1. Reopen the sqlplus session.

   2. Enter the following SQL commands:

      SQL> column OBJECT_NAME format a30;
      SQL> column STATUS format a10; 
      SQL> select object_name, status from user_objects where object_name='BISM_CORE';
      
      

      The following display indicates that the patch has been applied successfully:

      OBJECT_NAME                STATUS
      ------------------------------------------------ 
      BISM_CORE                  VALID
      BISM_CORE                  VALID
      

E.3 Migrating User Settings from Previous Releases

You can migrate user settings from the production release of Oracle9i JDeveloper (9.0.4) to Oracle JDeveloper10g. When you open Oracle JDeveloper10g for the first time, you are prompted to migrate your user settings from the previous version. By default, all settings are marked for migration. You should allow the user settings to be upgraded, especially the database connections. If those connections are not migrated, then you must re-create any connections that are referenced by BIDesigners that exist in any of the workspaces that you will migrate.

Oracle does not support direct migration from Oracle JDeveloper version 3.2.3 to Oracle9i JDeveloper (9.0.4) or later.

See Section A.2.1, "Migrating JDeveloper User Settings from Release 9.0.2 to Release 10.1.2" for more information about migrating user settings.

E.4 Migrating the BI Beans Workspaces

Perform the following steps in order to migrate the projects:

1. Before migrating any workspaces, create backup copies of those workspaces.

2. If you did not automatically migrate database connections as described in Section E.3, "Migrating User Settings from Previous Releases", then migrate those connections before proceeding. In Oracle JDeveloper10g, display the Connection Navigator, right-click Database, and choose Import Connections.

   Ensure that you complete this step before opening a BIDesigner that uses a connection from Oracle9i JDeveloper (9.0.4).

3. Allow JDeveloper to migrate the project.

   You should migrate a workspace that was created in Oracle9i JDeveloper (9.0.4) or a project that was created in Oracle9i JDeveloper (9.0.4) that you are now adding to a workspace in Oracle JDeveloper10g. If you start Oracle JDeveloper10g and open an BI Beans workspace from Oracle9i JDeveloper (9.0.4), then you will see the Migration wizard. This wizard can perform many migration steps automatically. For example, the wizard updates the workspace to the correct Oracle JDeveloper10g version. You can allow other options to run automatically, such as the update of the UIX Installables and the data binding syntax in HTML applications, as appropriate.

   You should allow the wizard to migrate any local Catalogs automatically. In the wizard, you can also specify whether to back up the Catalogs before migrating. If you do not want to migrate certain local Catalogs, then you can deselect them in the wizard. Refer to Section E.2, "Migrating the BI Beans Catalog" for information on upgrading remote Catalogs.

4. After the automatic upgrade completes, turn on Deprecation Warnings in the Compiler options, compile the application code to identify any deprecated classes or tags that you need to replace, and fix the errors that you see.

5. Edit the project settings by removing the following line to ensure that this option is not set. If this option is set, then JDeveloper uses the older version of JDBC rather than the newer version.

   -Djava.ext.dirs=C:\Jdev\JDev904_2.7.5.32.1\jdev\lib\patches

6. If the application contains a presentation and if you use the thin QueryBuilder to edit that presentation, then you might notice that the Start With page has no measures selected. To resolve this issue, complete the following steps:

   1. Edit the presentation in JDeveloper.

   2. Using the Items panel in the Presentation Editor, click OK or Apply.

   3. Redeploy the application from the design-time Catalog to the runtime Catalog.

7. Perform the appropriate steps that are described in the following sections, depending on the kind of application that you have:

   • Section E.4.1, "Manual Migration Steps for BI Beans JSP Applications"

   • Section E.4.2, "Manual Migration Steps for BI Beans UIX Applications"

   • Section E.4.3, "Manual Migration Steps for BI Beans Java-Client Class Applications"

   • Section E.4.4, "Manual Migration Steps for BI Beans Java Servlet Applications"

     
     

     Tip: See the Oracle Business Intelligence Tools Release Notes for the latest information on manual migration steps.

     
     

E.4.1 Manual Migration Steps for BI Beans JSP Applications

Perform the manual migration steps that are described in the following sections for JSP applications.

E.4.1.1 Updating the Namespace

Edit the namespace in the initial line of code in each page. Append "/jsp" to the existing namespace as shown in the following example:

Before edit:

<%& taglib uri="http://xmlns.oracle.com/bibeans" prefix="orabi" %>

After edit:

<%& taglib uri="http://xmlns.oracle.com/bibeans/jsp" prefix="orabi" %>

E.4.1.2 Accessing New BI JSP Tag Functions

If you want to access the JSP tag functions that are new to this release of BI Beans, then you must perform the following steps:

1. Add the following text to the top of all the JSP pages in the migrated application:

   <%@ taglib uri="http://java.sun.com/jstl/core" prefix="c"%>

2. Ensure that the JSTL tag libraries are in the project, by performing the following steps:

   1. Check the <project>\public_html\WEB-INF\lib directory to see if it contains the standard.jar file. If it does not, then perform Steps b and c.

   2. Open any JSP page in the migrated project. In the Component Palette, select JSTL Core. Drag the "out" tag to the page. Choose OK in the tag editor.

   3. In the JSP page, locate the <c:out></c:out> tag and remove it.

      Check the <project>\public_html\WEB-INF\lib directory again. The standard.jar file should be there.

E.4.1.3 Updating the <body> Tag

Update the HTML <body> tag in each page that contains a BIThinSession tag. After you edit the namespace, you must update the BIBody tag and the InitBITags tag. You can simply drag and drop the BIBody tag on the page when it is displayed in the Visual Editor. You can drag and drop the InitBITags tag as the first child of the form.

If the drag-and-drop technique is not effective, then you can edit the tags manually, as described in the following steps:

1. Remove the <body> tag and in its place insert the following required BI tags: BIBody (before the HTML <form> tag) and InitBITags (after the HTML <form> tag).

2. Set the action attribute of the <form> to the name of the JSP page.

3. Set the method attribute to POST.

4. Set the parentForm attribute of InitBITags to the name of the <form>.

The following code shows an example of these tags in a page named "biexplorerdetail1.jsp":

<orabi:BIBody>
<form name="BIForm" method="POST" action="biexplorerdetail1.jsp" >
<orabi:InitBITags parentForm="BIForm"/>

Note: Ensure that there are no slashes in the specification for the name of the JSP page. In addition, replace the end tag </body> with </orabi:BIBody>

E.4.1.4 Updating Code that Accessed a Presentation

If your application contains a scriplet in the JSP page or has Java code that accessed the presentation through its ID and cast it to a ThinDataviewCommon, then you must cast it to a Presentation bean and get the data view from the bean.

To accomplish this, change a line of code such as the following one:

ThinDataviewCommon dataView = (ThinDataViewCommon)pageContext.findAttribute
("biuntitled1_pres1");

to read like this:

ThinDataviewCommon tdvc = null;
Presentation p = (Presentation)pageContext.findAttribute
("biuntitled1_pres1"); 
if (p != null)
   tdvc = p.getView();

Add the following import to access the new Presentation bean:

oracle.dss.thin.beans.dataView.Presentation;

E.4.1.5 Updating the SaveButton JSP Tag

The SaveButton JSP tag has been replaced by the SaveLink tag. If your application uses the SaveButton JSP tag, then you can update the application by performing the following steps:

1. In the BIThinSession, locate a SaveButton tag that is similar to the following one:

   <orabi:SaveButton id="analyze1_SaveButton1" 
   presentationId="analyze1_Presentation1"
   saveConfirmationPage="saveconf1.jsp" 
   saveConfirmationId="saveconf1_SaveConfirmation1" />
   

   Modify the SaveButton tag to use the SaveLink tag, as shown in the following example:

   <orabi:SaveLink id="analyze1_SaveButton1" mode="Save" 
   presentationId="analyze1_Presentation1" />
   
   

2. Modify the Render tag for the SaveButton tag. For example, suppose that you have a Render tag that is similar to the following one:

   <orabi:Render targetId="analyze1_SaveButton1" parentForm="BIForm"/>
   
   

   Edit the Render tag so that it is similar to the following one:

   <orabi:Button text="Save" onClick="${analyze1_SaveButton1_data.showDialog}"/>
   
   

   When users click the Save button, they will see the internal save page.

E.4.2 Manual Migration Steps for BI Beans UIX Applications

Perform the manual migration steps that are described in the following sections for UIX applications. These steps assume that you used the UIX application that the BI Beans generated as the basis for your custom application.

E.4.2.1 Updating the Path of Images

If a workspace contains images, then you must copy the images and update the path of the images in the BIPageTemplate UIT file and in the login UIX file, as described in the following steps:

1. Update the source path for all the images in the BIPageTemplate UIT file and on the login UIX pages. In Oracle9i JDeveloper (9.0.4), the images are stored in the public_html\cabo\images\<app_name> directory. In Oracle JDeveloper10g, the images are stored in the public_html\<app_name> directory.

   For example, the specification for this directory is made in a tag such as the following one in the UIT file:

   <images source="cabo\images\<app_name>\required.gif">

   Modify this tag to read as follows:

   <images source="<app_name>\required.gif">

2. If the application uses custom images, then copy the images to the appropriate directory for Oracle JDeveloper10g, as specified in Step 1.

E.4.2.2 Updating the Error Page

While migrating, you might receive a message that describes a problem with the error page in the UIX application. To resolve this problem, you can take one of the following actions:

• If you want to use the default error page that is supplied automatically by BI Beans 10.1.2, then remove the previously existing error page before migrating the project to BI Beans 10.1.2.

• If you have customized the default error page and do not want to lose your modifications, then before migrating, edit the <bibeans:biPageTemplate> element and remove the renderLogoutButton attribute. For example, the element might read as follows:

  <bibeansTemplate:biPageTemplate 
       xmlns="http://xmlns.oracle.com/uix/ui" 
       xmlns:data="http://xmlns.oracle.com/uix/ui" 
       xmlns:ctrl="http://xmlns.oracle.com/uix/controller" 
      renderLogoutButton="false" 
      renderOpenButton="false" 
      pageTitle="BI uiXML Application Error"> 
  
  

  Simply edit the element to remove the text that reads:

  renderLogoutButton="false"

  After editing the element, modify the web.xml file. The error page entry reads as follows:

  <init-param> 
     <param-name>oracle.cabo.servlet.errorPage</param-name> 
     <param-value>cabo/bi/uix/error</param-value> 
  </init-param>
  
  

  Change the value cabo/bi/uix/error to point to your customized error page.

E.4.2.3 Adding an Element for Partial Page Rendering

You must edit template pages that use partial page rendering (PPR) functions. Add a <body> element to the application code, as shown in the following example:

<contents> 
    <body> 
       <contents> 
          <form name="form1" method="POST"> 
              <contents>

Ensure that you add a </body> tag at the appropriate location.

E.4.2.4 Adding Code for Each dialogLinkDef Element

In Oracle JDeveloper10g, to bind a dialogLink to the onClick attribute of a button, a link, or an image, you must bind to the dataObject of the dialogLink through the key, "showDialog". For example, assume that the id of a dialogLink is dlgLnk1, and it is defined in the BIThinSession, bisession1.

In Oracle9i JDeveloper (9.0.4), the code looks like this:

<button onClick="${bibeans:data().bisession1.dlgLnk1}"/>

In Oracle JDeveloper10g, the code looks like this:

<button onClick="${bibeans:data().bisession1.dlgLnk1_data.showDialog}"/>

E.4.2.5 Updating Code that Accessed a Presentation

If your application contains Java code that accesses the presentation through its ID and casts it to a ThinDataviewCommon, then you now must cast it to a Presentation bean and get the data view from the bean.

To accomplish this, change a line of code such as the following one:

ThinDataviewCommon dataview =
 (ThinDataViewCommon) pageObjects.get("<parameter>");

to read like this:

Presentation presentation = 
   (Presentation) pageObjects.get("<parameter>");
ThinDataviewCommon dataview = null;
if (presentation !=null)
   dataview=presentation.getView();

In the Java code for the previous version of the UIX application, there are two instances in which you must make this code change.

Add the following import to access the new Presentation bean:

oracle.dss.thin.beans.dataView.Presentation;

E.4.2.6 Updating the SaveDef UIX Tag

In the current release, the saveConfirmation tag has been deprecated and replaced by the SaveDef UIX tag. You should use the internal save dialog page, which is supplied automatically, rather than the saveConfirmation page.

For example, the original lines of code might look similar to the following ones:

<bibeans:saveDef id="saveBtn1" 
presentationId="pres1" 
saveConfirmationPage="SaveConfirm1.uix" 
saveConfirmationId="saveConf1" />

Rewrite the code so that it looks similar to the following line:

<bibeans:saveDef id="saveBtn1" presentationId="pres1" mode="Save" />

When users click the Save button, they will see the internal save page.

E.4.3 Manual Migration Steps for BI Beans Java-Client Class Applications

Perform the manual migration steps that are described in the following sections for applications that use the Java-client class:

E.4.3.1 Graph Code Changes

If you use a graph in the application, then you must make the following code change. Change the following line of code:

((GraphLayout) layout).setGraph((UIGraph) dv);

to read like this:

((GraphLayout) layout).setGraph((Graph) dv);

E.4.4 Manual Migration Steps for BI Beans Java Servlet Applications

Before migrating a servlet application, consider whether you have added many custom pages or functionality. If you have not added substantial customizations, then you can generate a JSP or UIX application and recreate any customizations there. By switching to a JSP or UIX application, you can easily take advantage of the powerful new features that are available in BI Beans.

If you want to migrate a servlet application, then perform the manual migration steps that are described in the following sections:

E.4.4.1 Updating the Installables in the Cabo Directory For Servlet Applications

When you migrate a JSP or UIX application, the installables in the cabo directory are updated automatically. These installables are not updated automatically for servlet applications. The cabo directory contains the UIX and BI Beans images, style sheet, and Javascript files, which have been updated between Oracle9i JDeveloper (9.0.4) and Oracle JDeveloper10g. Perform the following steps to update the installables in the cabo directory for servlet applications:

1. Navigate to the public_html directory of the project to be upgraded.

2. Rename the cabo directory to cabo.9.0.4.

3. Create a new UIX or JSP page using the same BIDesigner as in the servlet application.

   When the page is generated, it creates a new cabo directory for the project.

4. If your old directory (cabo.9.0.4) contained any other files (for example, if you created a new style sheet or .xss file or application-specific image files), then you must copy those files to the new cabo directory

5. (Optional) You can safely delete the new page that was created.

E.4.4.2 Consulting Samples for Servlet Applications

BI Beans ships with a set of servlet application samples. Consult these samples for best practices in handling servlet applications in Oracle JDeveloper10g. For example, see the code that affects the ViewToolbar and modify your application code accordingly. The ViewToolbar is not backward compatible.

E.5 Post-Migration Task for the BI Beans Catalog (Optional)

After migrating the Catalog, you might want to perform a post-migration task to improve performance.

E.5.1 Conditions when Catalog Post-Migration is Beneficial

If all of the following conditions are present, then consider performing the optional post-migration task:

• Use of an application that was migrated to BI Beans 10.1.2 from BI Beans 9.0.3 or BI Beans 10g (9.0.4).

• Use of a migrated BI Beans Catalog that is running on Oracle Database 10g.

• Detection of the following warning message in the standard ErrorHandler log while running the application:

  BIB-9549: The query has had missing level information inserted. You may wish to resave this query and its associated calculations and saved selections. (This message is followed by a list of the objects that had missing level information.)

Note: The Catalog post-migration task might also be beneficial to a BI Beans 10.1.2.1 application that was previously migrated from BI Beans 10g (9.0.4).

E.5.2 Reason for Message BIB-9549

Starting with the BI Beans 10.1.2 release, hierarchy and level information are stored for each dimension member reference within each query and its associated calculations and saved selections in the Catalog. Whenever an application requests the loading of an object that does not have this information stored in the Catalog, the query must search for the required information before it can complete the load operation. Message BIB-9549 indicates that the load operation was delayed while the query searched for missing information.

E.5.3 Post-Migration Task

To avoid a delay each time that an object with missing information is loaded, you can perform a one-time operation of loading and resaving each object in the Catalog using BI Beans 10.1.2.

Complete the following steps to load and resave objects:

1. In Oracle JDeveloper10g, under Local Catalog, double-click each object. This action opens the object.

2. Resave each object.

3. Copy each object to the remote Catalog.