Skip Headers
Oracle® Access Manager Upgrade Guide
10g (10.1.4.3)

Part Number E12495-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

12 Upgrading Your Identity System Customizations

Tasks in this chapter are intended for administrators who are responsible to upgrade and redeploy earlier Identity System customizations. Oracle recommends that you upgrade and then test your upgraded customizations in a small isolated environment.

Unless explicitly stated, the information in this chapter applies to both upgrade methods. The tasks you perform will depend on what was implemented in your earlier installation. You can skip any task that is not relevant for your earlier environment. This chapter includes the following topics:

12.1 Prerequisites and Guidelines

Before starting to upgrade any Identity System customizations, Oracle recommends that you:

After completing and testing each upgraded customization, Oracle recommends that you back up the directory containing the upgraded customization and store it in a new location.

12.2 Upgrading Auditing and Access Reporting for the Identity System

If your earlier installation was configured for auditing and access reporting, you must complete specific activities in this discussion before starting your Identity Server after the upgrade. If your earlier installation was not configured for auditing and access reporting, you can skip this discussion.

Oracle Access Manager 10g (10.1.4.0.1) supports the Unicode standard. The Oracle equivalent for the Unicode UTF-8 standard is the AL32UTF8 character set. The code used to process this character set resides within the libraries bundled with each Oracle Access Manager 10g (10.1.4.0.1) component and is installed automatically. To support all the languages available with Oracle Access Manager 10g (10.1.4.0.1), the definitions of auditing and reporting tables have changed.

WARNING:

Retain your earlier auditing database to preserve the original data. Simply upgrading or altering existing database instances and tables is not supported and could result in permanent truncation and loss of existing data.

After upgrading the first Identity Server, you must create a new database instance to operate with 10g (10.1.4.0.1). All Identity and Access Servers audit to the same database instance. Therefore, you need only create a new database instance following the upgrade of the first Identity Server (not for additional Identity Server instances nor for the Access Server).

You must upload the new Audit table schema (to support the auditing of 10g (10.1.4.0.1) UTF-8 data and the writing of this data to the new SQL Server instance). To accomplish this, you must create a new oblix_audit_events table for the auditing application. This schema upgrade includes datatype changes within the Audit table columns, as discussed in "Database Record Sizing".

Next you must create tables for the reporting application (oblix_rpt_as_reports, oblix_rpt_as_resources, and oblix_rpt_as_users) in 10g (10.1.4.0.1).

Note:

Whether you have only one or multiple Identity Server instances, you set up a new audit database instance, upload the audit schema, and create new tables for the reporting application only once.

To query or generate any report that requires data from both the old and new database, you must import data from the original database instance into the new instance before you start auditing with 10g (10.1.4.0.1). For each Identity Server instance (and Access Server instance), you import earlier audit data into the new audit database instance. Otherwise, you cannot generate any report that requires data from both the old and new database.

Note:

Be sure to retain the earlier database to preserve the original data. Importing earlier data can result in truncation of data and some data loss.

Finally, you must change the DSN (ODBC Data Source Name used by the RDBMS profile of audit & reporting applications) to refer to the new database instance. If you have multiple Identity Servers on the same computer, be sure to upgrade all instances on the computer before you change the DSN to refer to the new database. For each Identity Server instance (and Access Server instance), you must change the DSN to refer to the new database instance.

If you observe any problem with the characters (for example, Latin-1) after importing data and before auditing with 10g (10.1.4.0.1):

Even when you have an English only environment, certain steps depend on the type of database you are using. For more information, see:

12.2.1 Upgrading Auditing and Reporting with a Microsoft SQL Server

The default character set for the Microsoft SQL Server is UCS-2 (also known as UTF-16 Unicode format). UCS-2 includes all languages supported by Oracle Access Manager 10g (10.1.4.0.1) and mimics the way in which the 32-bit Windows kernel stores information so that data does not need to be converted to another format. As a result, no character set change is required for the Microsoft SQL Server for Oracle Access Manager 10g (10.1.4.0.1) globalization support.

Earlier data might be truncated during the import, as described in "Database Record Sizing".

Refer to the task overview here for the sequence of tasks you must perform. For more information about individual steps, including uploading the audit schema, see the Oracle Access Manager Identity and Common Administration Guide.

Task overview: Ugrading auditing and reporting with a Microsoft SQL Server

  1. Retain the original database, as is, to preserve your original data.

  2. After upgrading the first Identity Server (and before restarting the Identity Server Service), set up a new audit database instance for 10g (10.1.4.0.1) using instructions in the Oracle Access Manager Identity and Common Administration Guide.

  3. Create a new oblix_audit_events table for the 10g (10.1.4.0.1) auditing application (which will upload the 10g (10.1.4.0.1) schema definition). For information about uploading the audit schema, see the Oracle Access Manager Identity and Common Administration Guide.

  4. Create new oblix_rpt_as_reports, oblix_rpt_as_resources, and oblix_rpt_as_users. tables for the 10g (10.1.4.0.1) reporting application as described in the Oracle Access Manager Identity and Common Administration Guide.

    Note:

    You complete steps 1 through 4 for only the first Identity Server in your environment (even when you have multiple Identity Servers).
  5. Review information in "Database Record Sizing".

  6. Optional: Import the earlier data audited by this Identity Server instance into the 10g (10.1.4.0.1) database and confirm that it is imported successfully. You will repeat this step for each Identity Server instance.

    The serverId field in audit table indicates the ID of the Identity Server that audited that record. Based on the serverId field, it is feasible to differentiate the records audited by each Identity Server instance. The same rule applies to the Access Server, as discussed later.

  7. Change the DSN (ODBC Data Source Name used by the RDBMS profile of audit & reporting applications) on this computer to refer to the new database instance. For example:

    Note:

    If you have multiple Identity Servers on the same computer, be sure to upgrade all Identity Server instances on this computer before you change the DSN to refer to the new database. In this case, skip to step 9.

    Figure 12-1 Create a New Data Source to SQL Server Window

    Create a New Data Source to SQL Server Window
    Description of "Figure 12-1 Create a New Data Source to SQL Server Window"

  8. Start the Identity Server service.

    The Identity Server will now audit and store data in the new database instance. However, other Identity Servers (and Access Servers) will continue to audit and store data in the old database instance.

  9. Upgrade all other Identity Server instances as follows:

    • Upgrade the next Identity Server instance but do not restart the Identity Server service.

    • Repeat step 6 to import data for this Identity Server instance.

    • Repeat step 7 to change the DSN (ODBC Data Source Name used by the RDBMS profile of the audit & reporting applications) on this computer to refer to the new database instance.

      Note:

      If you have multiple Identity Servers on the same computer, be sure to upgrade all Identity Server instances on this computer before you change the DSN to refer to the new database.
    • Repeat step 8 to restart the Identity Server service on this computer.

    • Repeat this step (9) for all Identity Servers in your environment.

  10. After upgrading all Identity Server instances, upgrade all WebPass instances then complete the rest of the Identity System deployment-specific activities in this chapter before starting to upgrade the Access System.

  11. Start auditing, as described in the Oracle Access Manager Identity and Common Administration Guide.

12.2.1.1 Database Record Sizing

For the SQL Server, the maximum length of a database record is 8096 bytes. The Oracle Access Manager Audit table contains 27 columns (23 of which are of type varchar). The previous Oracle Access Manager (release 7.0.4, also available as part of Oracle Application Server 10g Release 2 (10.1.2)) record size was 23 columns * varchar(255) + four additional columns), which equals less than the SQL Server maximum of 8096 bytes for each database record.

To support UTF-8 data in Oracle Access Manager 10g (10.1.4.0.1), the column types have changed from varchar(255) to nvarchar(170). When the column data type is nvarchar, the SQL Server stores data in UTF-16 encoding. In this case, 23 columns * nvarchar(170) * 2 + four additional columns equals slightly less than 8096 bytes.

In earlier Oracle Access Manager releases, only values greater than 255 characters were truncated. In 10g (10.1.4.0.1), however, any column value that exceeds 170 characters is truncated before inserting the record into the SQL Server audit database.

For the reasons stated earlier, upgrading the existing database could result in permanent data loss. Therefore, with the SQL Server you must retain the original database as is, create and set up a new database, a new Audit Table for Oracle Access Manager with the 10g (10.1.4.0.1) schema definition, then create new auditing and reporting tables.

As stated earlier, you can import data from the original database instance into the new database instance (which might be truncated) in order to query or generate any report that requires data from both the old and new database. You will still have the original database instance and data.

See "Task overview: Ugrading auditing and reporting with a Microsoft SQL Server" and the Oracle Access Manager Identity and Common Administration Guide for more information.

12.2.2 Upgrading Auditing and Reporting with an Oracle Database

As described earlier, to support all the languages available with Oracle Access Manager 10g (10.1.4.0.1), the definitions of oblix_audit_events, oblix_rpt_as_reports, oblix_rpt_as_resources, and oblix_rpt_as_users tables have changed. After upgrading the first Identity Server, you create a new Oracle database instance with AL32UTF8 as character set and UTF-8 as National character set.

Note:

Upgrading the database instance and tables is not supported.

You must complete activities outlined in the task overview here because upgrading the database instance and tables is not supported. For more information about the steps, including uploading the audit schema, see the Oracle Access Manager Identity and Common Administration Guide and your vendor documentation.

Task overview: Ugrading auditing and reporting with an Oracle database

  1. Retain the original database as is, to preserve your original data for import.

  2. After upgrading the first Identity Server, set up a new Oracle audit database instance with AL32UTF8 as the character set and UTF8 as the National character set for the Oracle database. See also the Oracle Access Manager Identity and Common Administration Guide.

  3. Create a new oblix_audit_events table for the 10g (10.1.4.0.1) auditing application (which will upload the 10g (10.1.4.0.1) schema definition). For information about uploading the audit schema, see the Oracle Access Manager Identity and Common Administration Guide.

  4. Create new oblix_rpt_as_reports, oblix_rpt_as_resources, and oblix_rpt_as_users. tables for the 10g (10.1.4.0.1) reporting application as described in the Oracle Access Manager Identity and Common Administration Guide.

    Note:

    You complete steps 1 through 4 for only the first Identity Server in your environment (even when you have multiple Identity Servers).

    To query or generate any report that requires data from both the old and new database, you must import data from the original instance into the new instance before you start auditing with 10g (10.1.4.0.1).

  5. Import earlier data audited by this Identity Server instance into the 10g (10.1.4.0.1) database and confirm that it imported successfully using your Oracle database documentation for details.

    Note:

    You will repeat this step for each Identity Server instance. There is no truncation of data during the import, because the Audit table column size is 255 characters. If after importing data and before auditing with 10g (10.1.4.0.1) you observe any problem in characters (Latin-1), create a new database instance with the proper configuration (including but not limited to AL32UTF8 as character set and UTF-8 as National character set) and import your original again.
  6. Change the DSN (ODBC Data Source Name used by the RDBMS profile of audit & reporting applications) on this computer to refer to the new database instance. See your vendor documentation for details about performing this task. For example:

    Note:

    If you have multiple Identity Servers on the same computer, be sure to upgrade all Identity Server instances on this computer before you change the DSN to refer to the new database. In this case, skip to step 7.

    Figure 12-2 Microsoft ODBC for Oracle Window

    Microsoft ODBC for Oracle Window
    Description of "Figure 12-2 Microsoft ODBC for Oracle Window"

  7. Start the Identity Server service.

    The Identity Server will now audit and store data in the new database instance. However, other Identity Servers (and Access Servers) will continue to audit and store data in the old database instance.

  8. Upgrade all other Identity Server instances as follows:

    • Upgrade the next Identity Server instance but do not restart the Identity Server service.

    • Repeat step 5 to import data for this Identity Server instance.

    • Repeat step 6 to change the DSN (ODBC Data Source Name used by the RDBMS profile of the audit & reporting applications) on this computer to refer to the new database instance.

      Note:

      If you have multiple Identity Servers on the same computer, be sure to upgrade all Identity Server instances on this computer before you change the DSN to refer to the new database.
    • Repeat step 7 to restart the Identity Server service on this computer.

    • Repeat this step (8) for all Identity Servers in your environment.

  9. After upgrading all Identity Server instances, proceed with following activities:

12.3 Combining Challenge and Response Attributes on a Panel

In earlier releases, the challenge phrase and response attributes were allowed on different panels of the Profile page of the User Manager, Group Manager, and Organization Manager. In 10g (10.1.4.0.1), however, both the challenge phrase and response attributes must be on the same panel. In 10g (10.1.4.0.1), challenge phrases and responses are displayed one after the other even though these are not configured one after the other in the panel.

Note:

If your original installation included both the challenge phrase and response attribute on a single panel, you can skip this discussion.

If a panel contains only the challenge phrase attribute, it will be displayed on the Profile page without a response. If the panel contains only the response (without the challenge phrase), the response will not be displayed in Profile Page at all.

If challenge and response attributes are present in different panels in Identity System application configuration pages (User Manager Configuration, Group Manager Configuration, or Org. Manager Configuration), you must move these into a single panel.

The next task overview outlines the steps you will perform to combine the challenge phrase and response attributes on a single panel. For more information about configuring Tab Profile Pages and Panels, configuring attributes, and assigning challenge and response semantic types to attributes for lost password management, see the Oracle Access Manager Identity and Common Administration Guide.

The User Manager Configuration page was selected in this example. However, the procedure is similar if you modify panels on Group Manager Configuration or Org. Manager Configuration pages.

Task overview: Combine challenge and response attributes on a single panel

  1. Navigate to the Modify Panels page containing the Response attribute. For example:


    Identity System Console, User Manager Configuration
    Tabs existing_tab_link (for Response attribute panel)
    View Object Profile, Configure Panels
    panel_name, Modify

    The Modify Panel page appears.

  2. Remove the Response Attribute: From the list of attributes on the Modify Panel page, locate the Response attribute and select ---- from the list, then click the Save button.

  3. Add the Response Attribute: Navigate to the Modify Panel page containing the challenge phrase attribute, click the Add button, then select the Response attribute and click the Save button.


    Identity System Console, User Manager Configuration
    Tabs existing_tab_link (for Challenge attribute panel)
    View Object Profile, Configure Panels
    panel_name, Modify

IdentityXML changes have also been made for this feature. For details, see the Oracle Access Manager Developer Guide. See also "Challenge Response Might Not Convert Properly".

12.4 Confirming Identity System Failover and Load Balancing

Your earlier implementation might include failover between an Identity Server and the directory server. The Identity Server failover configuration has resided in the directory server profile since release 5.2. As a result, there is no migration of parameters from failover configuration files to directory profiles. Although the schema itself has changed, migration of these changes is performed automatically during the upgrade.

There is also no impact on Identity System connection pools. The values for Initial Connections and Maximum Connections specified in the Database Instance profile are retained and will operate as they did previously.

Note:

For concurrent authentication requests on NDS directory servers, Oracle recommends that you increase the connection pool size to something higher than the default (1) for the user directory profile using the System Console.

During the upgrade, you do not need to complete any special handling for failover or load balancing. After upgrading Identity System components, simply test to ensure that any failover or load balancing that you had previously configured for the Identity System is still operating as expected.

You can use the following procedure to view details in the Database Instance Profile before testing.

To view failover, load balancing, and connection pool details for the Identity System

  1. From the Identity System Console, select System Configuration, Directory Profiles.

  2. Under the heading Configure LDAP Directory Server Profiles, select the name of the Profile you want to check.

  3. On the Directory Server Profile page, confirm the servers that use the failover information and confirm that the information matches previous settings. For example:

    • Maximum Active Servers

    • Failover Threshold

    • Sleep For (Seconds)

    • Max. Session Time (Min.)

  4. Locate the Database Instances list on the Directory Server Profile page and select the name of the Database Instance Profile you want to check.

  5. In the Database Instance Profile, verify the values for Initial Connections and Maximum Connections.

  6. Make any changes needed and save the profile.

  7. Perform a test to ensure that everything is working as expected.

For more information about configuring failover and load balancing, see the Oracle Access Manager Deployment Guide.

12.5 Migrating Custom Identity Event Plug-Ins

When your original installation included custom Identity Event Plug-ins, Oracle recommends that you complete this activity immediately after upgrading all Identity System components.

Earlier Identity Event Plug-ins are not copied during the upgrade. At a minimum, you must move your earlier plug-ins from the renamed source directory to the target directory as indicated in the procedure here. To send or receive internationalized data you must re-design plug-ins to use UTF-8 encoding.

Solaris and Linux: Plug-ins earlier than release 7.x must be re-compiled using the GCC v3.3.2 C++ compiler. For more information, see "Plug-ins"

Note:

Release 7.0 plug-ins as well as earlier plug-ins implemented as executables or those using a scripting language (such as perl) do not require recompiling after the upgrade. However, to send and receive internationalized data, earlier plug-ins should be redesigned to communicate using UTF-8 encoding.

To use earlier custom Identity Event plug-ins with 10g (10.1.4.0.1)

  1. Create a folder in the top level of your Identity Event API directory and copy your earlier Identity Event plug-ins in to the new directory.

  2. Redesign Identity Event plug-ins to use UTF-8 encoding, if desired.

  3. Solaris and Linux: Recompile release 5.2 or 6.x plug-ins on platforms using the GCC v3.3.2 compiler.

    WARNING:

    You must use the GCC v3.3.2 compiler, regardless of the compiler that might be provided with the Operating System.

  4. Complete any testing to ensure your plug-ins are working properly with 10g (10.1.4.0.1).

  5. When using plug-ins that send and receive data in Latin-1 encoding, ensure that any new Identity Servers added to the upgraded environment are backward compatible as described in Chapter 4.

Authentication and authorization plug-ins also need to be recompiled or redesigned after the upgrade, as discussed in "Recompiling and Redesigning Custom Authentication and Authorization Plug-Ins".

12.6 Ensuring Compatibility with Earlier Portal Inserts

Oracle Access Manager 10g (10.1.4.0.1) cannot detect query string character encoding and assumes it to be UTF-8. An earlier Identity Server that you upgrade to 10g (10.1.4.0.1) has backward compatibility enabled to process Latin-1 data from earlier Portal Inserts. Oracle recommends that you change the encoding of the query string in earlier Portal Inserts from Latin-1 to UTF-8.

Note:

If you add a 10g (10.1.4.0.1) Identity Server to an upgraded environment, you must manually enable backward compatability with older plug-ins by including the Latin-1 encoding tag in IdentityServer_install_dir\identity\oblix\apps\common\bin\oblixpppcatalog.lst. For details, see the Oracle Access Manager Installation Guide.

10g (10.1.4.0.1) supports two encoding formats for IdentityXML requests: ISO-8859-1 (Latin-1) and UTF-8. The response, however, will be in UTF-8 encoding only. Within this required string you can use a tag to select an encoding specification:

For more information about customizing portal inserts, see the Oracle Access Manager Customization Guide.

12.7 About Custom Items and Upgrades

Customized .XSL style files, images, and JavaScript files are not migrated during the upgrade. If your previous installation includes significant changes to earlier XSL stylesheets, or if you use a style other than the Oracle Access Manager default Classic Style, you must manually include those changes in 10g (10.1.4.0.1) stylesheets, images, and JavaScript files.

WARNING:

If you simply copy earlier stylesheets, you might receive stylesheet bug reports or experience unpredictable behavior when using new features designed to work with new stylesheets.

When you view the Customize Styles page in the upgraded 10g (10.1.4.0.1), style names are listed to reflect the style definitions maintained in the directory server as Oracle Access Manager configuration data. However, it is important to note that the customized style files themselves are not migrated, which is why the procedures in this chapter are required.

To illustrate this, suppose a system-level change was made to the 10g (10.1.4.0.1) basic.xsl stylesheet to accommodate a new feature. In this case, copying an earlier release of basic.xsl to replace the 10g (10.1.4.0.1) basic.xsl will not guarantee that the new feature will work (because the new feature requires the 10g (10.1.4.0.1) basic.xsl stylesheet).

Note:

As discussed earlier, the directory structure has changed starting with Oracle Access Manager release 6.5 and continuing through 10g (10.1.4.0.1) to accommodate multiple languages. Of specific interest for activities in this chapter are the differences in the PresentationXML directories and message storage, described in Appendix A.

During the upgrade to 10g (10.1.4.0.1)

WARNING:

Do not attempt to copy earlier stylesheets to upgraded locations. Instead, you must use procedures in this chapter to alter new stylesheets so they reflect changes in earlier stylesheets.

The process you must complete to include earlier customized styles in the upgraded 10g (10.1.4.0.1) environment differ depending on your starting release. For more information, see the appropriate topic for your environment:

12.8 Incorporating Customizations from Release 6.5 and 7.x

Including customized styles from release 6.5 or 7.x in the upgraded 10g (10.1.4.0.1) environment is a fairly straight forward process.

Note:

Oracle recommends that you locate all recorded changes made in the release 6.5 or 7.x environment before starting and track all operations as you complete them in the 10g (10.1.4.0.1) environment.

To incorporate styles created with release 6.5 or 7.x

  1. Locate any information about changes and customizations made to the release 6.5 or 7.x environment to use those as a guide when completing the following tasks.

  2. Preserving Custom Styles Directories: Copy your release 6.5 or 7.x custom language-specific style directories from the renamed source to the 10g (10.1.4.0.1) Identity Server language directories. For example:


    From: IdentityServer_timestamp_install_dir/identity/oblix/lang/langtag/
    YourStyleName

    To: IdentityServer_install_dir/identity/oblix/lang/langtag/
    YourStyleName
  3. Preserving Custom Images: Copy your release 6.5 or 7.x (or new) custom images from the renamed source directory to the 10g (10.1.4.0.1) WebPass directories. For example:

    From: WebPass_timestamp_install_dir/identity/oblix/lang/langtag/style0

    To: WebPass_install_dir/identity/oblix/lang/langtag/style0

  4. Transferring Stylesheet Customizations: This is a multiple step process where you inspect individual messages from the release 6.5 or 7.x catalog to the 10g (10.1.4.0.1) catalog and manually copy these to the 10g (10.1.4.0.1) catalog. For example:

    • Inspect Earlier Message Changes and Additions: In your release 6.5 or 7.x renamed source directory, manually inspect any changes to messages in msgctlg.xsl (new messages added or original message was changed) in:


      From: IdentityServer_timestamp_install_dir/identity/oblix/lang/langtag
      /msgctlg.xsl
    • Copy Individual Message Changes: Manually edit the 10g (10.1.4.0.1) msgctlg.xsl file to match the release 6.5 or 7.x version.You can copy information from the release 6.5 or 7.x file into the 10g (10.1.4.0.1) version:

      To: IdentityServer_install_dir/identity/oblix/lang/langtag/msgctlg.xsl

    • Copy Individual Stylesheet Changes: In the release 6.5 or 7.x stylesheet in the renamed source directory, identify any changes then edit the 10g (10.1.4.0.1) stylesheet files to match the earlier version. You can copy any changes to the 10g (10.1.4.0.1) version.

  5. Preserving JavaScript Customizations: This is a two step process that must be performed for each installed language.

    • Inspect earlier message changes and additions: In the release 6.5 or 7.x renamed source directory, identify any JavaScript code changes in the msgctlg.js file, then manually copy these to the 10g (10.1.4.0.1) version. For example:

      From: WebPass_timestamp_install_dir/identity/oblix/lang/langtag/msgctlg.js

      To: WebPass_install_dir/identity/oblix/lang/langtag/msgctlg.js

    • Copy individual JavaScript customization: In the release 6.5 or 7.x renamed source directory, identify any Javascript code changes and then manually copy these to 10g (10.1.4.0.1).

For complete details about customized styles, see the Oracle Access Manager Customization Guide.

12.9 Incorporating Customizations from Releases Earlier than 6.5

If you have upgraded from release 6.5 or later (or your earlier installation did not include custom images, styles, or JavaScript that you want to use with 10g (10.1.4.0.1)), you can skip this discussion.

For a successful stylesheet upgrade, you must complete all procedures in this chapter. The stylesheet upgrade task has been divided into several functional procedures that you can use as a guide.

Task overview: Incorporating custom styles includes

  1. Completing activities in Style Customization Prerequisites.

  2. Recreating Custom Style Directories in 10g (10.1.4.0.1)

  3. Customizing New Stylesheets

  4. Incorporating Custom Images

  5. Using New Customized Styles

  6. Incorporating JavaScript Customizations

  7. Handling Language-Specific Message Catalogs

12.9.1 Style Customization Prerequisites

Before you begin upgrading stylesheets, check Table 12-1 to ensure you have properly prepared the environment for this task. Failure to complete prerequisites can adversely affect your upgrade.

Table 12-1 Identity Style Customization Prerequisites

Style Customization Prerequisites

Finish "Upgrading Remaining Identity System Components In Place" and confirm that the upgraded system is working properly

Review "About Custom Items and Upgrades".


12.9.2 Recreating Custom Style Directories in 10g (10.1.4.0.1)

As you re-create (add) custom style directories to Oracle Access Manager in following steps, you must use the same style names and the same style file system locations that were used before the upgrade. See the Oracle Access Manager Identity and Common Administration Guide for additional information.

To add custom styles in 10g (10.1.4.0.1)

  1. Complete tasks in "Style Customization Prerequisites".

  2. Log in to the upgraded Identity System Console and navigate to the Configure Styles page.

    For example:

    Identity System Console, System Configuration, Configure Styles

  3. Enable Classic Style as the default stylesheet if this is not currently the default.

  4. Delete the placeholders for your customized styles listed on the Customize Styles page.

    Note:

    You cannot delete the Classic Style maintained in the \style0 file system directory because this style is required by the Identity System Console.
  5. From the Customize Styles page, click the Add Style button.

    The Add Styles page appears.

  6. On the Add Style page, fill in the Name and (file system) Directory Name fields using the same style name and file system location used before the upgrade.

    For example:

    Name Pastel

    Directory Name Pastel

    The next step enables Oracle Access Manager to create the appropriate file system directory structure automatically and copy the upgraded default stylesheets into it.

  7. Select Classic Style in the Copy From list, then click the Save button.

    For example:

    Copy From Classic Style

    Save

    Your new custom style directory duplicates \style0 and contains wrapper stylesheets that point to default global stylesheets in the \shared directory (when you selected Copy From Classic Style).

  8. Repeat previous steps 4 through 7, to re-create in Oracle Access Manager each customized style from the earlier installation.

    For additional information, see the Oracle Access Manager Identity and Common Administration Guide

    The new style name is listed in the Customize Styles page and one or more directories were created to hold the new wrapper stylesheets.

  9. Select a new style as your default style, as follows:

    1. Click the Setup Default Style button to display the Set Default Style page.

    2. Click the Make Default button beside your new style name, then click Save.

  10. Check your file system for the new style directory name you specified.

You are ready to start the next procedure, "Customizing New Stylesheets", to include earlier customizations in the new stylesheets.

12.9.3 Customizing New Stylesheets

At this point, you must edit a copy of each new-default stylesheet using your own originally customized files as a guide. It is a good idea to take notes about your work as you go.

Locating and selectively copying stylesheets is an iterative process that you complete one stylesheet at a time, as described in the Oracle Access Manager Customization Guide, including:

  • Base stylesheets

  • Stylesheets included in base stylesheets

  • Specific function-related stylesheets identified for the program in the application's registration file

  • Stylesheets included in the function-related stylesheet

To verify that a stylesheet has been successfully applied, just launch the page and perform a visual check.

Task overview: Customizing New Stylesheets

  1. Complete the procedure "Recreating Custom Style Directories in 10g (10.1.4.0.1)".

  2. Follow the steps in the procedure "To customize new stylesheets" to:

    • Locate, in the renamed source directory, a customized earlier stylesheet to use as a reference.

    • Locate, in your new custom directory, the wrapper stylesheet that corresponds to your earlier customized stylesheet.

    • Locate, in your upgraded \shared directory, the default stylesheet that corresponds to the new wrapper.

    • Overwrite the new wrapper stylesheet in your new custom style directory with the new-default stylesheet from the 10g (10.1.4.0.1) \shared directory.

    • Edit the new-default stylesheet using your earlier customized file as a guide.

  3. Replace messages in stylesheets, as described in "Handling Language-Specific Message Catalogs".

See the Oracle Access Manager Customization Guide for more information about stylesheet structure and content, and how to customize these.

WARNING:

Do not copy the original customized file into any upgraded directory. Do not copy content from the original customized file into any upgraded file. Do not attempt to copy all new-default stylesheets into your custom directory at once.

Remember that your new custom style directory duplicates the default \style0 and contains wrapper stylesheets that point to default stylesheets in the \shared directory. You cannot be assured that a wrapper file will be called before the actual stylesheet because both the common registration file and the application's own registration file call stylesheets according to an internal ordering.

In addition, the stylesheets in the \shared directory are used with all languages and applications and should be retained as is. Eventually your custom directory will contain a copy of all stylesheets, including those identified in the application's registration file and in oblixbasereg.xml. Even if you do not need to edit a stylesheet, it must be copied to your custom directory.

Note:

For the Access System, there are only JavaScript changes; no stylesheets. You must update the stylesheet for each "style" directory for each language. Oracle recommends that you perform these steps to retain all customizations for one language first, then simply copy the updated file to other "style" directories and remaining languages.

To customize new stylesheets

  1. In the renamed source directory created during the upgrade, select and open one original customized stylesheet file.

    For example:

    \IdentityServer_install_dir_timestamp\identity\oblix\apps\AppName\ui\style0\name.xsl
    
  2. In your new custom directory, locate and open the wrapper stylesheet that corresponds to your earlier customized stylesheet.

    For example:

    \IdentityServer_install_dir\identity\oblix\lang\en-us\Pastel\name.xsl
    
  3. In the new wrapper stylesheet, review the "include href=" statements for files that are included and record these names and paths.

    For example:

    <?xml version="1.0" encoding="ISO-8859-1"?>
    - <!--    Copyright (c) 1996-2005, Oracle Inc. All Rights Reserved. -->
    - <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:oblix="http://www.oblix.com/">
    <xsl:include href="./name.xsl" />
    <xsl:include href="../name.xsl" />
    <xsl:include href="../../shared/name.xsl" />
    </xsl:stylesheet>
    

    Next you must overwrite the wrapper file in your new custom directory with a copy of the new-default stylesheet you intend to customize.

  4. In the 10g (10.1.4.0.1) \shared directory, locate and copy the new-default stylesheet that corresponds to your original customized stylesheet, as indicated:

    Copy From \shared

    \IdentityServer_install_dir\identity\oblix\lang\shared\name.xsl
    

    Copy To new custom directory

    \IdentityServer_install_dir\identity\oblix\lang\en-us\Pastel\name.xsl
    
  5. In your new custom directory, locate and edit the copied-default stylesheet to reflect changes made to the earlier customized file, and record your changes.

  6. Repeat the steps in this list as you locate and copy each related default stylesheet to your new custom directory, then customize it to match changes in the earlier customized release:

    • Base stylesheets

    • Stylesheets included in base stylesheets

    • Specific function-related stylesheets identified for the program in the application's registration file

    • Stylesheets included in the function-related stylesheet

  7. Ensure that file system access control for your new custom style directories and files is set to match the ownership and permissions of \style0.

  8. Restart the Identity Server.

  9. To verify that a stylesheet has been successfully applied, just launch the page and perform a visual check.

  10. Continue with "Incorporating Custom Images".

12.9.4 Incorporating Custom Images

If your earlier installation did not include custom images that you want to use with 10g (10.1.4.0.1), you can skip this discussion.

In earlier versions of Oracle Access Manager, images were distributed throughout the installation directory and referred to with respect to the application path. From 10g (10.1.4.0.1) onward, images are language dependent and are consolidated into a single directory. When installations include multiple languages, you will have multiple \langTag directories. For directory details, see Appendix A.

  • Identity System images are in the directory:

    \WebPass_install_dir\identity\oblix\lang\langTag\style0

  • Access System images are in the following directory:

    \install_dir\access\oblix\lang\langTag\style0

Note:

All common images require a copy for each language.

12.9.4.1 gifPathName and jsPathName Variables

Due to the change in location of all image files, a new gifPathName variable is defined in wrapper stylesheet style.xsl. In addition to style.xsl, the msgctlg.js file also includes the gifPathName variable to mention the path for image locations:

IdentityServer_install_dir\oblix\lang\langTag\style0\style.xsl
IdentityServer_install_dir\oblix\lang\langTag\msgctlg.js

A language independent stylesheet in the \shared directory picks up the images from the modified image path mentioned by the gifPathName variable. This is important for two reasons:

  • It prevents hard-coding of URLs in the stylesheets and makes it easier to reuse the same stylesheet across styles.When customizing stylesheets, you should use this global variable whenever constructing a URL path to a GIF or other image.

  • It incorporates the current language and current style tag and generates the correct path.

Note:

Stylesheets refer to the gifPathName variable to locate the image directory. JavaScript files refer to the jsPathName variable.

For more information about msgctlg files, see "Handling Language-Specific Message Catalogs".

Example—style.xsl with variables highlighted

The style.xsl wrapper resides in the \style0 directory and can reside in your custom directory:


IdentityServer_install_dir\identity\oblix\lang\en-us\style0\style.xsl
IdentityServer_install_dir\identity\oblix\lang\en-us\Custom\style.xsl
<?xml version="1.0" encoding="ISO-8859-1"?>
- <!--    Copyright (c) 1996-2005, Oracle Inc. All Rights Reserved. -->
- <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:oblix="http://www.oblix.com/">
  <xsl:variable name="styleName">style0</xsl:variable>
  <xsl:variable name="localeName">en-us</xsl:variable>
- <xsl:variable name="gifPathName">
  ../../../lang/
  <xsl:value-of select="$localeName" />
  /
  <xsl:value-of select="$styleName" />
  </xsl:variable>
  <xsl:variable name="jsPathName">../../../lang/shared</xsl:variable>
  ...   </xsl:stylesheet>

Note:

You must replace the image path in the 10g (10.1.4.0.1) stylesheet you are modifying.

For 10g (10.1.4.0.1), you must reference images using the two variables ($gifPathName and jsPathName) to make your customization language and style independent. To do so, modify your 10g (10.1.4.0.1) stylesheet with the corresponding <img src="{$gifPathName}/<custom gif name>.gif"/> reference as described in the next procedure.

To incorporate custom images

  1. Copy all custom images from the renamed source directory to the target (repeat this for each language):

    Fromsource_directory_timestamp

    To targetWebPass_install_dir\identity\oblix\lang\langTag\style0

  2. Copy all custom images for the Access System from the source directory to the target:

    Fromsource_directory_timestamp

    To targetinstall_dir\access\oblix\lang\langTag\style2

  3. Modify the image source path name in 10g (10.1.4.0.1) stylesheets in your custom directory:

    For example:

    \IdentityServer_install_dir\identity\oblix\lang\Pastel

  4. For Releases Before 6.5: Change image path to use the $gifPathName variable.

    For example, suppose the image source is mentioned in the Oracle Access Manager 6.1 stylesheet:

    install_dir\oblix\apps\common\ui\style0\navbar.xsl

    as:

    <img src="../../common/ui/style0/T1oblixnetpoint.gif"/>
    

    You must change the image path for 10g (10.1.4.0.1) as follows:

    <img src="{$gifPathName}/T1oblixnetpoint.gif"/>
    
  5. See also:

12.9.5 Using New Customized Styles

Before you can use the new customized style, you must complete the task here.

Note:

Due to extensive coverage in the Oracle Access Manager Customization Guide. The specific details are outlined but not repeated here.

Task overview: Using new customized styles

  1. Copy images and styles to WebPass to create a custom style directory structure on WebPass and include all images in this structure, as described in the Oracle Access Manager Customization Guide.

  2. Test your customized style, as described in the Oracle Access Manager Customization Guide.

  3. Propagate new stylesheets to other Identity Servers and WebPass hosts, as described in the Oracle Access Manager Customization Guide.

  4. Continue with:

12.9.6 Incorporating JavaScript Customizations

If your earlier installation did not include JavaScript customization that you want to use with 10g (10.1.4.0.1), you can skip this discussion.

In 10g (10.1.4.0.1), JavaScript files are located in:

WebPass_install_dir\identity\oblix\lang\shared

Like stylesheets, language-specific pop-up messages in JavaScript files are replaced with variables defined in:

install_dir\identity\oblix\lang\langTag\msgctlg.js

JavaScript files are not present in the \lang\langTag directory except in the msgctlg.js file. The steps needed to migrate JavaScript files are similar to those you used earlier to migrate stylesheet changes.

To incorporate JavaScript files

  1. In the time-stamped source directory created during the upgrade, locate your earlier customized JavaScript files on the computer hosting the upgraded WebPass.

  2. In the 10g (10.1.4.0.1) \lang\shared directory on the WebPass, locate and copy your new-default JavaScript files to retain for future use.

  3. Edit the 10g (10.1.4.0.1) JavaScript files in the \lang\shared directory on the WebPass to reflect changes made in the earlier release and record your changes, or see "Handling Language-Specific Message Catalogs".

12.9.7 Handling Language-Specific Message Catalogs

All custom styles are stored under the \langtag directories, even when your customized functionality is language independent. The procedure here applies to environments that are upgraded from releases prior to 6.5 because these have embedded message customizations in the stylesheet itself. This only applies to 6.1 customers using single language. If the changes are done for English, then the product will pick up the English message properly.

As discussed elsewhere, multiple languages are available for use with 10g (10.1.4.0.1). Messages that were once in stylesheets are language dependent and are now defined separately as variables in message catalogs. See also Appendix A.

The new Oracle Access Manager directory structure consolidates all message catalogs for JavaScript files, XSL, and HTML.

  • As the name suggests any language-specific files will be located in \lang\langTag.

  • Any non-language specific objects are located within \lang\shared.

All the stylesheets have a language-specific wrapper in \lang\langTag\style0 which includes the main language-neutral release stylesheet in \lang\shared. This new wrapper segregates the main stylesheet functionality, which is language independent, from language-specific messages.

Language-specific messages are referred to through variables in message catalog files, as discussed in:

12.9.7.1 Handling XSL Stylesheet Messages

The messages for stylesheets are defined in the message catalog:

\IdentityServer_install_dir\identity\oblix\lang\langTag\msgctlg.xsl

You must ensure that all displayable strings in your earlier stylesheets are placed in the 10g (10.1.4.0.1) stylesheet message catalog.

For example, suppose you have customized a Oracle Access Manager 6.1 stylesheet, navbar.xsl, in:

\IdentityServer_install_dir\identity\oblix\apps\common\ui\style0\navbar.xsl

where a message reads as:

<xsl:text> &lt;&lt; Click here to return to the previous application(s).
    </xsl:text>

In the 10g (10.1.4.0.1) stylesheet:

\IdentityServer_install_dir\identity\oblix\lang\shared\navbar.xsl

you should modify the message to read:

<xsl:text> &lt;&lt; <xsl:value-of select="$MPrevAppln"/> </xsl:text>

and ensure that MPrevAppln is defined in the 10g (10.1.4.0.1) message catalog:

\IdentityServer_install_dir\identity\oblix\lang\langTag\msgctlg.xsl

as follows:

<xsl:variable name="MPrevAppln">Click here to return to the previous
    application(s). </xsl:variable>

To handle language-specific message catalogs for XSL stylesheets

  1. Locate the earlier stylesheet containing the customized message.

    For example:

    \IdentityServer61_install_dir\identity\oblix\apps\common\ui\style0\navbar.xsl

    <xsl:text> &lt;&lt; Click here to return to the previous application(s). </xsl:text>
    

    If you have already copied the stylesheet to your custom directory, skip to step 3.

  2. If you have not yet overwritten the wrapper file with the corresponding stylesheet, copy the corresponding 10g (10.1.4.0.1) stylesheet to your custom directory.

    For example:

    Copy from

    \IdentityServer_install_dir\identity\oblix\lang\shared\navbar.xsl

    Copy to

    \IdentityServer_install_dir\identity\oblix\lang\langTag\Custom_dir\navbar.xsl

  3. In the 10g (10.1.4.0.1) stylesheet in your custom directory, modify the message to use the appropriate message catalog parameter.

    For example:

    <xsl:text> &lt;&lt; <xsl:value-of select="$MPrevAppln"/> </xsl:text>
    
  4. In the 10g (10.1.4.0.1) message catalog, ensure that the message parameter is defined.

    \IdentityServer_install_dir\identity\oblix\lang\langTag\msgctlg.xsl

    <xsl:variable name="MPrevAppln">Click here to return to the previous    
         application(s). </xsl:variable>
    
  5. Restart the Identity Server and WebPass so the changes take affect.

12.9.7.2 Handling Messages for JavaScript

Language-specific pop-up messages in JavaScript are also replaced by variables, which are defined in:


\WebPass_install_dir\install_dir\identity\oblix\lang\langTag\msgctlg.js

This message catalog is divided into sections that show the messages for specific JavaScript files, several of which are named:


misc.js ... atickets.js wfqs.js deactivateuser.js confirm.js ...

You must ensure that all displayable strings are placed in the message catalog, and the message catalog must be referenced through the I18N_GetMsg function.

For example, the code in the earlier JavaScript file:

\install_dir\identity\oblix\apps\admin\bin\admin.js

that pops up a message:

alert("Room must have a name.")

now appears in:

\WebPass_install_dir\identity\oblix\lang\shared\admin.js

as:

alert(I18N_GetMsg('MRoomNameReq'))

where MRoomName is defined in:

\WebPass_install_dir\install_dir\identity\oblix\lang\langTag\msgctlg.js

as:

MESSAGE_CATALOG[ 'MRoomNameReq' ] = "Room must have a name.";

Note:

Oracle recommends that you do not customize files in the \shared directory and, instead, copy files from \shared into your custom directory before customizing.

To handle language-specific message catalogs for JavaScript files

  1. Ensure that all displayable strings are placed in the 10g (10.1.4.0.1) message catalog:

    \WebPass_install_dir\identity\oblix\lang\langTag\msgctlg.js

  2. Ensure that the 10g (10.1.4.0.1) message catalog is referenced through the I18N_GetMsg function (which is automatically loaded) located in:

    \WebPass_install_dir\identity\oblix\lang\shared\i18n.js

  3. Restart the Identity Server and WebPass so changes take affect.

12.10 Validating Identity System Customization Upgrades

Oracle recommends that you test your upgraded Identity System customizations in a test or development environment before deploying these in an upgraded production environment.

To validate Identity System customization upgrades

  1. Verify that your customizations have been restored properly by performing specific operations that will exercise the upgraded customizations. For example, for workflow PPP plug-ins you run appropriate workflows.

  2. Verify that auditing and access reporting is working properly.

  3. Perform a visual inspection of the user interface if you customized any stylesheets and the like.

  4. Upgrade Not Successful: Proceed to "Recovering from an Identity System Customization Upgrade Failure".

  5. Upgrade Successful: Proceed to "Backing Up Upgraded Identity System Customizations" next.

12.11 Backing Up Upgraded Identity System Customizations

As mentioned earlier, Oracle recommends that you finish each upgrade by backing up the appropriate 10g (10.1.4.0.1) directory. This will enable you to easily restore your environment to the newly upgraded state should that be a requirement.

To back up Identity System customizations after the upgrade

  1. Back up the 10g (10.1.4.0.1) directory that contains the upgraded Identity System customizations and store it in a new location.

  2. Proceed as described in "Looking Ahead".

12.12 Recovering from an Identity System Customization Upgrade Failure

If an Identity System customization was not successful, you can perform the following steps to rollback this upgrade, then try again.

To recover from an unsuccessful Identity System customization upgrade

  1. Restore the earlier customization files or directory that you backed up before the upgrade (to recover the earlier customization), then back it up again. You will retain one as a backup copy and use one in the next step.

  2. Using a backup copy of your earlier customization files, restart the upgrade as described in this chapter.

12.13 Looking Ahead

After ensuring that your previous Identity System customizations are integrated and operating properly in the upgraded environment, see Chapter 13 for details about upgrading Access System customization upgrades.

If you do not have an Access System in your environment, proceed to validating your upgraded environment as described in Chapter 14. If you are using the zero downtime upgrade method, see also Part VI.