IBM Atlas Suite V6.0.1 Upgrade Guide

Transcription

1 IBM Atlas Suite V6.0.1 Upgrade Guide

2 IBM Atlas Suite V6.0.1 Upgrade Guide This edition applies to version 6.0 of IBM Atlas Suite (product numbers 5725-D75, 5725-D76, 5725-D77) and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright International Business Machines Corporation 2004, US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

3 Contents 1 Introduction System Requirements Upgrading the Oracle Database Before You Begin Prepare to Upgrade Run the Upgrade Script After the Upgrade Where to Go Next Upgrading IBM Atlas Suite Applications What you Need Copy the IBM Atlas Suite Files Merge your Previous Configuration Changes Prepare the WebLogic Domain Clear the Application Server Cache JBoss log4j Logging (upgrade from pre-v6 only) Deploy the IBM Atlas Suite Applications Where to Go Next ActiveX Control How to Handle Alert Translation Failure (pre-v6 upgrade only)... 16

4 1 Introduction This document tells you how to upgrade IBM Atlas Suite from version 4.5, 5.0.1, or 6.0 to version After you ve finished upgrading, you must install the most recent Fix Pack, and then configure the system as described in IBM Atlas Suite Administrators Guide: System Configuration. I M P O R T A N T I M P O R T A N T After you upgrade to IBM Atlas Suite V6.0.1, you must install the most recent Fix Pack. If you uninstall your IBM Atlas Suite deployment, make sure you delete this file: ATLAS/Properties/Licenses/Atlas_Suite swtag where ATLAS is the IBM Atlas Suite home directory. 1.1 System Requirements The system requirements for IBM Atlas Suite V6.0.1 are listed here:

5 2 Upgrading the Oracle Database This chapter steps you through the process of upgrading the Oracle database. To perform the instructions in this chapter, you must have Oracle SYSDBA privileges. I M P O R T A N T Before you upgrade to IBM Atlas SuiteV6.0.1, you should create a backup copy of your database. 2.1 Before You Begin Before you begin, you must gather some information and locate some files that are in your current installation Gather Database Information The hostname (or IP address) and port of your database server. The examples in this chapter refer to this information as DBHost and DBPort. The TNS name of the database instance or net service that you want to connect to (TNSName). The database SID (referred to as DBName). The name and password of a SYSDBA account (SYS/SYSPWD. The name and password of the Atlas schema owner (PSSAPL/PSSAPLPWD). The name and password of the Atlas web user account (PSSWEBUSER/PSSWEBUSERPWD). The name and password of the Atlas Reports user account (PSSRPTUSER/PSSRPTUSERPWD). The names of the tablespaces that were created for Atlas (PSS_USER and PSS_TEMP). The database schema includes an optional Monitor Job that sends a red flag if the Legal Notice or Alert system isn t working properly. If you use the Monitor Job and you ve upgraded your database, you ll need: The host name and port number of your SMTP server (MailHost, MailPort). The address of the person who should receive the (MailTo). The address that s used as the From: address in the (MailFrom). If you don t have this information during initial deployment, you can return and set it later IBM Atlas Suite Administrators Guide: System Configuration. To use the Monitor Job, your database server must be able to access your SMTP server.

6 Upgrading the Oracle Database IBM Atlas Suite V6.0.1 Upgrade Guide Locate Properties Files (upgrade from pre-v6 only) If you re upgrading from IBM Atlas Suite v4.5 or v5.0.1, you ll be asked for copies of your current appstrings.properties and msgstrings.properties files. These files live in the ATLAS/Properties directory on the application server machine that hosts the Atlas application. N O T E You don t need to retrieve the files if you re upgrading from v Prepare to Upgrade 1 Create the Atlas home directory (referred to as ATLAS in these instructions). If you re using the same database client machine that you used to install the previous release, you should already have an Atlas home directory. If you do, you should first move the directory to a new location. For example: $ mv ATLAS c:/atlas5.0.1 $ mkdir ATLAS 2 Open the IBM Atlas Suite V6.0.1 archive and copy /Atlas/Schema into the Atlas home directory, thus creating an ATLAS/Schema directory. 3 If you re upgrading from IBM Atlas Suite v4.5 or v5.0.1, copy the appstrings.properties and msgstrings.properties files into this directory: ATLAS/Schema/Deploy/smf/db/release/default/oracle/upgrade/ _to_ /alerts/ config N O T E The _to_ portion of the path is correct regardless of which release you re upgrading from and to. 4 Open the database configuration file in a text editor: ATLAS/Schema/Deploy/smf/db/etc/oracle/smf_properties.ini 5 Look for the [Connection] section and replace the highlighted placeholders with actual values. ; Connection properties [Connection] DATABASE_USER = PSSAPL DATABASE_USER_PASSWORD = PSSAPLPWD Connecting to a database instance DATABASE_NAME = TNSName DATABASE_URL = jdbc:oracle:thin:@dbhost:dbport:dbname --or-- DATABASE_URL = jdbc:oracle:thin:@//dbhost:dbport/dbname DATABASE_JAVA_PRIV = N ER_ENABLED = N Connecting to a net service If you re connecting directly to a database instance, use the first form of the DATABASE_URL value. If you re connecting through a net service, use the second form. The DBName value must be the real, non-tns database SID or net service name. 6

7 IBM Atlas Suite V6.0.1 Upgrade Guide Upgrading the Oracle Database If you re using an External Repository, change the ER_ENABLED and DATABASE_JAVA_PRIV flags to Y. If you re not using an External Repository, leave them both as the default (N).To enable the External Repository after you ve deployed the database, see the IBM Atlas Suite Administrators Guide: System Configuration book. 6 If you want to use the Atlas Monitor Job, look for the [MailServer] section and replace the placeholders with actual values: ; Mail Server properties [MailServer] MAIL_HOST = MailHost MAIL_FROM = MailFrom MAIL_TO = MailTo SMTP_PORT = MailPort To configure the Monitor Job after you ve deployed the database, see the IBM Atlas Suite Administrators Guide: System Configuration book. 7 If you want to enforce unique Person Identifier values in the Person records, set UNQ_PERSONIDENTIFIER to Y (it s N by default): ; Data Integrity properties [DI] UNQ_PERSONIDENTIFIER = Y 8 Save and close the smf_properties.ini file. 9 Set the PA_HOME environment variable to point to this directory: ATLAS/Schema/Deploy 10 Start your Oracle database if it isn t already running. 11 Stop all Oracle jobs that service IBM Atlas Suite. How you find and stop the Oracle jobs depends on your environment. The IBM Atlas Suite distribution doesn t include tools or instructions for stopping the jobs. 12 Stop all Atlas applications (Atlas, AtlasLink, and Atlas Reports). 13 In a command window, drop and then recreate the PSSWEBUSER and PSSRPTUSER users: $ cd ATLAS/Schema/Deploy/smf/db/release/default/oracle/create/user/ $ sqlplus PSSWEBUSER $ sqlplus PSSRPTUSER $ sqlplus PSSWEBUSER PSS_USER PSS_TEMP $ sqlplus PSSRPTUSER PSS_USER PSS_TEMP I M P O R T A N T You should change the PSSWEBUSER and PSSRPTUSER passwords after you ve recreated the users. By default, the passwords are the same as the user names. 14 If you ve upgraded your Oracle database, connect to the database as SYSDBA and execute this command: SQL> alter system set "_replace_virtual_columns" = false; 7

8 Upgrading the Oracle Database IBM Atlas Suite V6.0.1 Upgrade Guide 15 If you re using the Monitor Job and you ve upgraded your Oracle database, execute the grant_acl_sendmail.sql script, passing in the arguments shown below. This will give the Monitor Job sufficient privileges to send $ sqlplus PSSAPL MailHost MailPort 2.3 Run the Upgrade Script Run the script that upgrades the schema $ cd ATLAS/Schema/Deploy/smf/db/etc/python Windows: $ run-script.bat upgradeschema.py -v oracle > install.log UNIX: $./run-script.sh upgradeschema.py -v oracle > install.log You may see some warning messages as the script is running. Warnings can be ignored: Warning: Function created with compilation errors. Warning: Procedure created with compilation errors. ### WARNING: Section is empty: [UPGRADE] If the upgrade fails, you ll see an error or failure message and the upgrade will abort: *** ERROR: Invalid DB Vendor: orracle. *** FAILURE: Script failed: create_all_trg.sql The one failure that you can fix yourself is this: *** FAILURE: Data Integrity Check Fail *** FAILURE: See ATLAS/Schema/Deploy/smf/db/log/duplicate_report.log for report To fix the error, see the instructions in the next subsection, Fixing the Data Integrity Check Failure. For all other errors or failures, consult your IBM ECM Client Technical Professional. If the upgrade was successful, you ll see a series of!!! SUCCESS messages, culminating in the announcement of the new Atlas version:!!! SUCCESS: Upgrade scripts executed successfully!!!! SUCCESS: Upgraded to target version: The upgrade messages are also written to the install.log file. ATLAS/Schema/Deploy/smf/db/log/duplicate_report.log 8

9 IBM Atlas Suite V6.0.1 Upgrade Guide Upgrading the Oracle Database Fixing the Data Integrity Check Failure The Data Integrity Check failure means that you enabled the unique Person Identifier feature and the upgrade script found duplicate or empty Person Identifier values in your Person table. To fix this failure, open this report file: ATLAS/Schema/Deploy/smf/db/log/duplicate_report.log The report file lists the Person Identifier errors in this form: The following rows on PERSON table have NULL or duplicate PersonIdentifier PersonIdentifier LoginID PersonID NULL attorney NULL attorney AB27601 abaltz 2344 AB27601 Baltz 2316 AD20952 adelisio 2359 AD20952 Delisio 2331 Each row identifies a single error. Records that are missing the Person Identifier value show NULL in the PersonIdentifier column. The rest of the entries are sorted alphabetically by Person Identifier value, so duplicates are easy to identify. The LoginID column is the Person s Login ID string, and PersonID is the record ID in the database. Fix the errors in your database and then re-run the upgrade script Alert Translation Status (upgrade from pre-6.0 only) If you re upgrading from IBM Atlas Suite v4.5 or v5.0.1, the Alert objects (individual Alert records) that are stored in your database will be translated into a new form. Near the end of the upgrade, the script will display an assessment of the success of the translation, in this form: Alert Translation Status: [java] - 10,223 Alerts were translated successfully. [java] Alerts failed to be translated: [java] - 6 Alerts couldn't be classified. [java] Alerts were classified, but without a Matter ID. For guidance on how to handle translation failures, see the How to Handle Alert Translation Failure chapter. 2.4 After the Upgrade 1 If the schema upgrade was successful, grant privileges to PSSWEBUSER and PSSRPTUSER $ cd ATLAS/Schema/Deploy/smf/db/release/default/oracle/create/user/ $ sqlplus PSSWEBUSER $ sqlplus PSSRPTUSER 2 Restart the Oracle jobs that service IBM Atlas Suite. 9

10 Upgrading the Oracle Database IBM Atlas Suite V6.0.1 Upgrade Guide 2.5 Where to Go Next After you ve finished upgrading the database, go to the next chapter and upgrade the IBM Atlas Suite applications. 10

11 3 Upgrading IBM Atlas Suite Applications This chapter tells you how to upgrade the IBM Atlas Suite applications in a WebLogic, WebSphere, or JBoss application server. This chapter should be used by an application server administrator. I M P O R T A N T I M P O R T A N T If you re upgrading your application server at the same time that you re upgrading Atlas, you should completely redeploy Atlas as described in the IBM Atlas Suite V6.0.1 Deployment Guide. You must configure and start your database before you can use this chapter. 3.1 What you Need To perform the operations in this chapter, you need the location of your IBM Atlas Suite home directory from the previous release. The examples in this chapter call the directory ATLAS. 3.2 Copy the IBM Atlas Suite Files 1 Halt the Atlas applications in your application server. 2 Log into the machine that hosts the application server. 3 Move your current Atlas home directory to a new location, and then recreate the home directory. For example: $ mv ATLAS c:/atlas5.0.1 $ mkdir ATLAS 4 Open the IBM Atlas Suite V6.0.1 archive and copy the contents of the /Atlas directory into the Atlas home directory. 3.3 Merge your Previous Configuration Changes The ATLAS/Properties directory and subdirectories contain a number of files that are used to configure various aspects of Atlas. If you made any changes to these files when you configured your previous version of IBM Atlas Suite, you must merge the changes into the new versions of the files. This includes new icons that you may have added to the application (to represent custom Data Source media types, for example).

12 Upgrading IBM Atlas Suite Applications IBM Atlas Suite V6.0.1 Upgrade Guide Most of the configuration files that you might have changed are directly in the ATLAS/Properties directory; however, make sure that you check your old versions of the files in ATLAS/Properties/defaultimpl/db, as well. These files configure the Puller Agents that are used by Atlas Extensions. 3.4 Prepare the WebLogic Domain If you re using WebLogic as you re application server, you must run a script that adds libraries to your domains and modify the script that starts the server. In the instructions, below, ATLAS_DOMAINS is the directory that contains the individual domain directories, and Domain is: AtlasSuite if you re configuring the domain that hosts Atlas and Atlas Extensions. AtlasReports if you re configuring the domain that hosts Atlas Reports. You ll perform the instructions twice, once for the AtlasSuite domain and again for AtlasReports Add Libraries to Your Domain To copy the Atlas libraries into your domain, run the setup script as shown below: Windows: $ cd ATLAS/setup/Weblogic $ setup.bat ATLAS_DOMAINS/Domain UNIX: $ cd ATLAS/setup/Weblogic $./setup.sh ATLAS_DOMAINS/Domain Edit the Startup Script How you edit the WebLogic startup script depends on whether you re using a Windows or UNIX machine Windows Open ATLAS_DOMAINS/Domain/bin/startWebLogic.cmd in a text editor and augment the SAVE_CLASSPATH variable as shown below. When you re finished, save and close the file. set SAVE_CLASSPATH=%CLASSPATH%;ATLAS\Properties;ATLAS\reports;ATLAS\reports\properties N O T E If your version of startweblogic.cmd script doesn t contain a SAVE_CLASSPATH variable, add the Atlas directories to the CLASSPATH variable. 12

13 IBM Atlas Suite V6.0.1 Upgrade Guide Upgrading IBM Atlas Suite Applications UNIX Open ATLAS_DOMAINS/Domain/bin/startWebLogic.sh in a text editor and augment the SAVE_CLASSPATH variable as shown below. When you re finished, save and close the file. set SAVE_CLASSPATH= "${CLASSPATH}${CLASSPATHSEP}ATLAS/Properties${CLASSPATHSEP}ATLAS/reports${CLASSPATHSEP} ATLAS/reports/properties" N O T E If your version of startweblogic.cmd script doesn t contain a SAVE_CLASSPATH variable, add the Atlas directories to the CLASSPATH variable. 3.5 Clear the Application Server Cache When you upgrade to a new version of IBM Atlas Suite, you have to clear the data that the application server has cached for the Atlas applications. You do this by removing directories that are contained in the AtlasSuite and AtlasReports domain or profile directories. The directories that you need to remove depend on the application server that you re using: WebLogic cache tmp WebSphere temp wstemp JBoss tmp work/jboss.web/localhost/ 3.6 JBoss log4j Logging (upgrade from pre-v6 only) The log4j logging configuration for JBoss was enhanced in IBM Atlas Suite v6. If you re using JBoss and you re upgrading from a v4.5 or v5.0.1 release, see the instructions in the Configure Logging section of the JBoss Configuration chapter of the IBM Atlas Suite V6.0.1 Deployment Guide. 13

14 Upgrading IBM Atlas Suite Applications IBM Atlas Suite V6.0.1 Upgrade Guide 3.7 Deploy the IBM Atlas Suite Applications Next, you ll deploy each of the IBM Atlas Suite applications in your application server. The new executable files are: Atlas Suite Atlas Extensions Atlas Reports ATLAS/EAR/PolicyAtlas.ear ATLAS/WAR/AtlasExtensions.war or ATLAS/EAR/AtlasExtensions.ear ATLAS/WAR/AtlasReports.war or ATLAS/EAR/AtlasReports.ear N O T E AtlasExtensions.ear and AtlasReports.ear are (simply) wrappers around the respective.war files. They re provided for customers that want to deploy EAR files rather than WAR files. If you re not sure how to deploy an application, consult your application server documentation. 3.8 Where to Go Next When you ve finished upgrading, you must install the most recent Fix Pack for IBM Atlas Suite V After that, you should review your system s configuration, as described in IBM Atlas Suite Administrators Guide: System Configuration.. 14

15 4 ActiveX Control After upgrading, the ActiveX Control that s installed on Atlas users machines so they can upload collected files might become obsolete. In this case, the user is prompted to download and install a new version. If your company doesn t allow users to download and install applications themselves, you ll need to install the new ActiveX Control for them, as described in the ActiveX Control chapter of the IBM Atlas Suite V6.0.1 Deployment Guide.

16 5 How to Handle Alert Translation Failure (pre-v6 upgrade only) If you re upgrading from a v4.5 or v5.0.1 release, the Alert records that already exist in the database are converted into a new form that includes a tokenized classification. Each type of Alert Notice transmission error, Local Schedule approval request, Data Source change, and so on has its own classification. This conversion supports a number of new features in IBM Atlas Suite v6: Alerts can be designated as being more or less severe. There are three severity levels, Warning, Important, and Critical. You designate the severity of each type of Alert in the new Admin > Matter Exceptions and Alerts module. The severity designation is used to filter the Alerts that are displayed in the My Alerts tray on the My Atlas page. The Alert types that are associated with Matters are now displayed in the Matters module. The success of the Alert translation is announced by the upgrade script near the end of its run, in this form: Alert Translation Status: [java] - 10,223 Alerts were translated successfully. [java] Alerts failed to be translated: [java] - 6 Alerts couldn't be classified. [java] Alerts were classified, but without a Matter ID. As implied here, there are two ways a translation can fail: An Alert might not have been classified at all. In the Admin > Matter Exceptions and Alerts module, these Alerts are designated as Other. Like all genuine Alert types, the Other type has a single severity designation. Because of this, the severity filtering in the My Alerts tray could fail to find some of the Alerts that you re interested in. For example, let s say you designate the Notice Bounced Alert as Critical and set your My Alerts tray to only display Critical Alerts. If the Alert translation process fails to translate some Notice Bounced Alerts, those Alerts won t be displayed in your list of Critical Alerts. A Matter Alert might be properly classified, but the translation process might not have been able to ascertain the Matter that the Alert is associated with. These Alerts will be filtered properly in the My Alerts tray, but they won t show up in the Matter s list of Alerts (in the Matters module). Translation failure isn t catastrophic your old Alerts won t be deleted, you just won t be able to take advantage of the new features. A handful of translation failures may be tolerable for your system s users. However, if the number of failures exceeds your tolerance, here s what you can do: Make sure you ve copied the appstrings.properties and msgstrings.properties files from your most recent IBM Atlas Suite v4.5 or v5.0.1 deployment into this directory (as described in the Upgrading the Oracle Database chapter): ATLAS/Schema/Deploy/smf/db/release/default/oracle/upgrade/ _to_ /alerts/con fig

17 IBM Atlas Suite V6.0.1 Upgrade Guide How to Handle Alert Translation Failure (pre-v6 upgrade only) There should be two other files in that same directory: REF_appStrings.properties REF_msgStrings.properties. These are included in the IBM Atlas Suite distribution. If these files are missing, copy them from the V6.0.1 distribution. After you ve made sure the files are in place, run the Alert translation script on the database client machine: Windows: $ cd ATLAS/Schema/Deploy/smf/db/release/default/oracle/upgrade/ _to_ /alerts/ $./run-standalone.bat UNIX: $ cd ATLAS/Schema/Deploy/smf/db/release/default/oracle/upgrade/ _to_ /alerts/ $./run-standalone.sh When the script finishes, it will produce a summary of its success. If some Alerts still can t be translated problem, consult your IBM ECM Client Technical Professional. 17