A Supplementary Upgrade Information

Use the additional information in this Appendix as a supplement to Chapter 13, "Upgrading to Oracle Identity Manager 9.0.1 from Versions 8.5.2 or 8.5.3" and Chapter 14, "Upgrading to Oracle Identity Manager 9.0.1 from Version 9.0.0" to assist you in the upgrade process.

Creating a User Profile Audit File Group in SQL Server

User Profile Audit is one of the new features introduced in Oracle Identity Manager 9.0.1. For performance reasons, UPA tables are placed in a separate file group called XELL_UPA, which must be created by your database administrator before you upgrade Oracle Identity Manager. Complete the following steps to create the new file group.

From the Windows Start Menu, select Programs, select Microsoft SQL Server, then select Enterprise Manager.
In the left pane of the SQL Server Enterprise Manager application window, select Console Root, select Microsoft SQL Servers. select the server group to which your server belongs, then double-click the icon representing the server on which your database is running.
Double-click Databases, right-click the database that needs to be upgraded, then click Properties.
Click the Data Files tab, specify the filename and location of the .NDF file as well as the amount of space allocated for this file.
Add a new filegroup named XELL_UPA.
Click OK.

Executing the SQL Server Upgrade Script

The upgrade package includes command line scripts that will upgrade the Oracle Xellerate Identity Provisioning 8.5.x or 9.0.0 SQL Server database and associated stored procedures to Oracle Identity Manager 9.0.1. These command line scripts execute a set of SQL Server scripts through the OSQL interface on the SQL Server database. All the command line scripts take the following five parameters.

Table A-1 Parameters for Command Line Scripts

Arguments	Description
<server-name[\instance-name]>	The name of the server under the ÒSQL Server GroupÓ in Enterprise Manager. \instance-name represents the instance running under the server.
<db-user>	The database user ID
<password>	The password of db-user
<db-name>	The name of the database
<script-location>	The absolute path to the command line script

For example:

To upgrade the database, run the batch file <Patch>/Database/SQLServer/Scripts/upg_852_853_to_901.bat, with the following command-line arguments:
```
<Patch>/Database/SQLServer/Scripts/upg_852_853_to_901.bat <server-name[\instance-name]> <db-user> <password> <db-name> <Patch>/Database/SQLServer/Scripts    
```
Note:
If you are upgrading to Oracle Identity Manager 9.0.1 from Oracle Xellerate Identity Provisioning 9.0.0, you will be using upg_900_to_901.bat in the preceding example.

To compile the new stored procedures, run <Patch>/Database/SQLServer/StoredProcedures/compile_all_XL_SP.bat with the following command-line arguments:

<Patch>/Database/SQLServer/StoredProcedures/compile_all_XL_SP.bat <server-name[\instance-name]> <db-user> <password> <db-name> <Patch>/Database/SQLServer/StoredProcedures

To enable the Oracle Identity Manager Audit and Compliance module, run the batch file <Patch>/Database /SQLServer/Scripts/SQLServer_Enable_XACM.bat, with the following command-line arguments:
```
SQLServer_Enable_XACM.bat <server-name[\instance-name]> <db-user> <password> <db-name> <Patch>/Database/SQLServer/Scripts
```

Loading Metadata into the Database

You must load certain metadata into your database by completing the following steps:

As appropriate for the operating system of the machine hosting your Oracle Identity Manager server, edit either LoadXML.bat or LoadXML.sh located in <Patch>/Database/Utilities/ and update the value for the variable JAVA_HOME.
As appropriate for your database and operating system of the machine hosting your Oracle Identity Manager server, complete one of the following sub-steps:

SQL Server and Windows
1. Launch a plain-text editor, open the file LoadXML.bat, and uncomment the following line:
```
REM SET SQL_SERVER_DRIVER_DIR=
```
2. Assign the path to the SQL Server driver directory that contains the msbase.jar, msutil.jar and mssqlserver.jar files:
```
SET SQL_SERVER_DRIVER_DIR=<PATH_TO_SQL_DRIVER>
```
SQL Server and Linux
1. Launch a plain-text editor, open the file LoadXML.sh, and uncomment the following line:
```
#SQL_SERVER_DRIVER_DIR=
#export SQL_SERVER_DRIVER_DIR
```
2. Assign the path to the JDBC driver for SQL Server, so that the line reads something like the following:
```
SQL_SERVER_DRIVER_DIR=<PATH_TO_SQL_DRIVER>
export SQL_SERVER_DRIVER_DIR
```
Oracle and Windows
1. Launch a plain-text editor, open the file LoadXML.bat, and uncomment the following line:
```
REM SET ORACLE_DRIVER_DIR=
```
2. Assign the path to the Oracle driver directory containing the Oracle JDBC drivers:
```
SET ORACLE_DRIVER_DIR=<PATH_TO_ORACLE_DRIVER>
```
Oracle and Linux
1. Launch a plain-text editor, open the file LoadXML.sh, and uncomment the following line:
```
#ORACLE_DRIVER_DIR=
#export ORACLE_DRIVER_DIR
```
2. Assign the path to the JDBC driver for Oracle, so that the line reads something like the following:
```
ORACLE_DRIVER_DIR=<PATH_TO_ORACLE_DRIVER>
export ORACLE_DRIVER_DIR
```
Open a command prompt or console and run the <Patch>/Database/Utilities/LoadXML.bat or LoadXML.sh script with the following command line parameters in the specified order for the type of database you are using:

Oracle
1. JDBC URL (example: jdbc:oracle:thin:@<db_host_ip>:<port>:<SID>)
2. Database user name
3. Password
SQL Server
1. JDBC URL (example: jdbc:microsoft:sqlserver://<ipaddress>:<port>)
2. Database name
3. Database user name
4. Password

Upgrading the Server Configuration File

The primary configuration file for Oracle Identity Manager, which is named xlconfig.xml, has been updated for the 9.0.1 release. If you are upgrading from Oracle Xellerate Identity Provisioning version 8.5.x to Oracle Identity Manager 9.0.1, you must add or modify parameters in this file, as detailed in the following sub-sections.

Adding New Configuration Parameters

Add the following configuration parameters to your version 9.0.1 configuration file:

Launch a plain-text editor, then open xlconfig.xml, which resides in the directory <XL_HOME>/xellerate/config/.

Locate the parameter <xl-configuration>.<Offlining>. .<MessageHandlerMDB>.<message-handler-task>.

Note:

Refer to "Conventions" for more information on identifying and locating xml tags.

Insert the following block of lines:

<AuditorOfflineMessage>com.thortech.xl.audit.engine.jms.XLAuditMessageHandler</AuditorOfflineMessage>
<AttestationRequestMessage>com.thortech.xl.schedule.jms.attestation.processOfflinedAttestationRequests</AttestationRequestMessage>
<AttestationTaskMessage>com.thortech.xl.schedule.jms.attestation.processOfflinedAttestationTasks</AttestationTaskMessage>
<AttestationWorkflowTaskMessage>com.thortech.xl.schedule.jms.attestation.processOfflinedAttestationWorkflowTasks</AttestationWorkflowTaskMessage>
<ProcessOfflineMessage>com.thortech.xl.schedule.jms.processOfflineProcesses.processOfflinedProvisioningProcesses</ProcessOfflineMessage>
<ProcessTaskOfflineMessage>com.thortech.xl.schedule.jms.processTaskOffline.processOfflinedProcessTask</ProcessTaskOfflineMessage>

after the string:

<xl-configuration>.<Offlining>.<MessageHandlerMDB>.<message-handler-task>.<ReconOfflineMessage>

but before the string:

<xl-configuration>.<Offlining>.<MessageHandlerMDB>.<message-handler-task>.<TestMessage>

Locate the configuration parameter <xl-configuration>.<Offlining>, then navigate to the space that starts after the following string:

<xl-configuration>.<Offlining>.</recon_offline_queue>

and before the following string:

<xl-configuration>.<Offlining>.<test_queue>

Note:

Refer to "Conventions" for more information on identifying and locating xml tags.

Insert the following block of lines into the space between the preceding two strings:

<auditor_offline_queue>
   <queueName>queue/xlQueue</queueName>
   <autoAcknowledge>true</autoAcknowledge>
   <replyTo></replyTo>
   <persistentFlag>true</persistentFlag>
   <disableMessageId>true</disableMessageId>
   <disableTimeStampe>false</disableTimeStampe>
   <messageEncrypt>false</messageEncrypt>
</auditor_offline_queue>
<attestation_request_queue>
   <queueName>queue/xlQueue</queueName>
   <autoAcknowledge>true</autoAcknowledge>
   <replyTo></replyTo>
   <persistentFlag>true</persistentFlag>
   <disableMessageId>true</disableMessageId>
   <disableTimeStampe>false</disableTimeStampe>
   <messageEncrypt>false</messageEncrypt>
</attestation_request_queue>
<attestation_task_queue>
   <queueName>queue/xlQueue</queueName>
   <autoAcknowledge>true</autoAcknowledge>
   <replyTo></replyTo>
   <persistentFlag>true</persistentFlag>
   <disableMessageId>true</disableMessageId>
   <disableTimeStampe>false</disableTimeStampe>
   <messageEncrypt>false</messageEncrypt>
</attestation_task_queue>
<attestation_workflow_task_queue>
   <queueName>queue/xlQueue</queueName>
   <autoAcknowledge>true</autoAcknowledge>
   <replyTo></replyTo>
   <persistentFlag>true</persistentFlag>
   <disableMessageId>true</disableMessageId>
   <disableTimeStampe>false</disableTimeStampe>
   <messageEncrypt>false</messageEncrypt>
</attestation_workflow_task_queue>
<process_offline_queue>
       <queueName>queue/xlQueue</queueName>
       <autoAcknowledge>true</autoAcknowledge>
       <replyTo></replyTo>
       <persistentFlag>true</persistentFlag>
       <disableMessageId>true</disableMessageId>
       <disableTimeStampe>false</disableTimeStampe>
        <messageEncrypt>false</messageEncrypt>
</process_offline_queue>
<process_task_offline_queue>
    <queueName>queue/xlQueue</queueName>
     <autoAcknowledge>true</autoAcknowledge>
     <replyTo></replyTo>
     <persistentFlag>true</persistentFlag>
     <disableMessageId>true</disableMessageId>
     <disableTimeStampe>false</disableTimeStampe>
     <messageEncrypt>false</messageEncrypt>
</process_task_offline_queue>

Add the XML snippet <BlockMode>ECB</BlockMode> under the following two locations:
- <xl-configration>.<Security>.<XLSymmetricProvider>.<Keys>.<DBSecretKey>
- <xl-configration>.<Security>.<XLSymmetricProvider>.<Keys>.<JMSKey>
Save and close the file.

Updating Existing Configuration Parameters

Complete the following steps to update existing configuration parameters:

Change the value of the following tag from ConnectionFactory to java:/JmsXA:
```
<xl-configuration>.<Discovery>.<JMSServer>.<connectionFactory>
```
If you are upgrading an existing, non-clustered 8.5.x environment to a clustered, version 9.0.1 environment, change the value of the following tag from false to true on all cluster members:
```
<xl-configuration>.<Scheduler>.<Clustering>
```

Locate the tag:

<xl-configuration>.<RMSecurity>.<LoggerConfigFilePath>

change it to the following value:

<XL_RM_HOME>/xlremote/config/log.properties

Upgrading the Metadata File

The metadata file containing information related to user interface forms has been updated for Oracle Identity Manager 9.0.1. Complete the following steps to configure this metadata file:

Launch a plain-text editor, then open the file FormMetaData.xml, which resides in the directory <XL_HOME>/xellerate/config/.
Locate the XML element <FormManagementMetaData>.<Attribute name="-30">.

Change the value of dataLength from 256 to 30. For example, change something like the following string:

<Attribute name="-30" label="Group Name" displayComponentType="TextField" variantType="String" dataLength="256" map="Groups.Group Name" />

to something like the following string:

<Attribute name="-30" label="Group Name" displayComponentType="TextField" variantType="String" dataLength="30" map="Groups.Group Name" />

Navigate to the end of the file, then locate the following line:

</FormManagementMetaData>

Insert the following block just preceding the line </FormManagementMetaData>. (In other words, the inserted block should become the last XML elements under the document root <FormManagementMetaData>)

This is the block to insert:

<!-- List of attributes that will be displayed in the "Attestation Wizard" -->
<Attribute name="-31" label="Groups" displayComponentType="LookupField" variantType="long" dataLength="50" map="Groups.Group Name">
<ValidValues lookupMethod="findGroups"            operationClass="Thor.API.Operations.tcGroupOperationsIntf" displayColumns="Groups.Group Name" selectionColumn="Groups.Group Name" permission="write"/>
</Attribute>
<Attribute name="-32" label="Groups1" displayComponentType="LookupField" variantType="long" dataLength="50" map="Groups.Group Name">
<ValidValues lookupMethod="findGroups" operationClass="Thor.API.Operations.tcGroupOperationsIntf" displayColumns="Groups.Group Name" selectionColumn="Groups.Group Name"/>
</Attribute>
<Attribute name="-33" label="Resources" displayComponentType="LookupField" variantType="long" dataLength="50" map="Objects.Name">
<ValidValues lookupMethod="findObjects" operationClass="Thor.API.Operations.tcObjectOperationsIntf" displayColumns="Objects.Name" selectionColumn="Objects.Name"/>
</Attribute>
<Attribute name="-34" label="Users" displayComponentType="LookupField" variantType="long" dataLength="50" map="Users.User Name">
<ValidValues lookupMethod="getActiveUsers" operationClass="Thor.API.Operations.tcUserOperationsIntf" displayColumns="Users.User ID,Users.Last Name,Users.First Name" selectionColumn="Users.User ID" permission="write"/>
</Attribute>

Upgrading the Remote Manager Configuration File

The primary configuration file for the Remote Manager has been updated for the 9.0.1 release. If you are upgrading from Oracle Xellerate Identity Provisioning version 8.5.x to Oracle Identity Manager 9.0.1, you must add or modify parameters in the file xlconfig.xml, as detailed in the following sub-sections.

Adding New Configuration Parameters

Complete the following steps to add JMS-related parameters to the Remote Manager configuration file:

Launch a plain-text editor, then open xlconfig.xml, which resides in the directory <XL_RM_HOME>/xlremote/config.

Locate the parameter <xl-configuration>.<Offlining>, then find the line:

Locate the parameter <xl-configuration>.<Offlining>, then find the line:

Insert the following block:

<AuditorOfflineMessage>com.thortech.xl.audit.engine.jms.XLAuditMessageHandler</AuditorOfflineMessage>
<AttestationRequestMessage>com.thortech.xl.schedule.jms.attestation.processOfflinedAttestationRequests</AttestationRequestMessage>
<AttestationTaskMessage>com.thortech.xl.schedule.jms.attestation.processOfflinedAttestationTasks</AttestationTaskMessage>
<AttestationWorkflowTaskMessage>com.thortech.xl.schedule.jms.attestation.processOfflinedAttestationWorkflowTasks</AttestationWorkflowTaskMessage>
<ProcessOfflineMessage>com.thortech.xl.schedule.jms.processOfflineProcesses.processOfflinedProvisioningProcesses</ProcessOfflineMessage>
<ProcessTaskOfflineMessage>com.thortech.xl.schedule.jms.processTaskOffline.processOfflinedProcessTask</ProcessTaskOfflineMessage>

after the following line:

<xl-configuration>.<Offlining>.<MessageHandlerMDB>.<message-handler-task>.<ReconOfflineMessage>

and preceding the following line:

<xl-configuration>.<Offlining>.<MessageHandlerMDB>.<message-handler-task>.<TestMessage>

Locate the following parameter:
```
<xl-configuration>.<Offlining>
```

Insert the following block:

<auditor_offline_queue>
   <queueName>queue/xlQueue</queueName>
   <autoAcknowledge>true</autoAcknowledge>
   <replyTo></replyTo>
   <persistentFlag>true</persistentFlag>
   <disableMessageId>true</disableMessageId>
   <disableTimeStampe>false</disableTimeStampe>
   <messageEncrypt>false</messageEncrypt>
</auditor_offline_queue>           
<attestation_request_queue>
   <queueName>queue/xlQueue</queueName>
   <autoAcknowledge>true</autoAcknowledge>
   <replyTo></replyTo>
   <persistentFlag>true</persistentFlag>
   <disableMessageId>true</disableMessageId>
   <disableTimeStampe>false</disableTimeStampe>
   <messageEncrypt>false</messageEncrypt>
</attestation_request_queue>
<attestation_task_queue>
   <queueName>queue/xlQueue</queueName>
   <autoAcknowledge>true</autoAcknowledge>
   <replyTo></replyTo>
   <persistentFlag>true</persistentFlag>
   <disableMessageId>true</disableMessageId>
   <disableTimeStampe>false</disableTimeStampe>
   <messageEncrypt>false</messageEncrypt>
</attestation_task_queue>
<attestation_workflow_task_queue>
   <queueName>queue/xlQueue</queueName>
   <autoAcknowledge>true</autoAcknowledge>
   <replyTo></replyTo>
   <persistentFlag>true</persistentFlag>
   <disableMessageId>true</disableMessageId>
   <disableTimeStampe>false</disableTimeStampe>
   <messageEncrypt>false</messageEncrypt>
</attestation_workflow_task_queue>
<process_offline_queue>
       <queueName>queue/xlQueue</queueName>
       <autoAcknowledge>true</autoAcknowledge>
       <replyTo></replyTo>
       <persistentFlag>true</persistentFlag>
       <disableMessageId>true</disableMessageId>
       <disableTimeStampe>false</disableTimeStampe>
        <messageEncrypt>false</messageEncrypt>
</process_offline_queue>
<process_task_offline_queue>
    <queueName>queue/xlQueue</queueName>
     <autoAcknowledge>true</autoAcknowledge>
     <replyTo></replyTo>
     <persistentFlag>true</persistentFlag>
     <disableMessageId>true</disableMessageId>
     <disableTimeStampe>false</disableTimeStampe>
     <messageEncrypt>false</messageEncrypt>
</process_task_offline_queue>

after the following line:

<xl-configuration>.<Offlining>.</recon_offline_queue>

and preceding the following line:

<xl-configuration>.<Offlining>.<test_queue>

Note:

Refer to "Conventions" for more information on identifying and locating xml tags.

Save and close the file.

Updating Existing Configuration Parameters

To update Remote Manager-related configuration parameters.

Launch a plain-text editor, then open xlconfig.xml, which resides in the directory <XL_RM_HOME>/xlremote/config.
Locate the <xl-configuration>.<RMSecurity>.<LoggerConfigFilePath> tag and change it to the following value:
```
<XL_RM_HOME>/xlremote/config/log.properties
```