Appendix A   Migrating from ECXpert 3.0 to Current ECXpert

This appendix describes the planning and tasks you must perform to upgrade from ECXpert Version 3.0 to current ECXpert.

The following topics are covered:

• Migrating from ECXpert 3.0 to Current ECXpert



•  Updating Stored Procedures for Billing Code Addition



• Removing the Previous Installation and Database Backup








---

Note	With the release of ECXpert 3.5, support is no longer available for ECXpert 1.1.1 and 2.0 migrations.

---

Migrating from ECXpert 3.0 to Current ECXpert

---

This section describes all of the steps you must perform to migrate from ECXpert 3.0 to the current ECXpert version.

Upgrading to Oracle 8.1.6

If you have not already done so, you will need to upgrade to Oracle 8.1.6, Enterprise Edition. See the included Oracle documentation for installing version 8.1.6 or contact your Oracle service provider or dba to assist in this process. Also, the Oracle Installation/Migration provides preinstallation information for Oracle 8.1.6.

---

Note	When you upgrade Oracle, do not create a new Oracle user to own the ECXpert tables. You must use the existing Oracle user who owns the ECXpert tables.

---

Set up and Test Your Database Connectivity 

Set up and test your database to be sure that user root has access to the database, so you can successfully migrate ECXpert. If user root doesn't have access to the database, you will get error messages during the ECXpert migration process.

1. Log in as user root.




# su - root



2. Determine the shell that root uses.




# echo $SHELL



The output of this command identifies the shell that root uses, which determines its associated environment file:




Output	Shell Being Used	Environment File
/sbin/sh	Bourne	.profile
/sbin/csh	C	.cshrc
/sbin/ksh	Korn	.profile or .kshrc

3. Determine the shell that oracle uses.




# cat /etc/passwd | grep oracle



The output of this command lists the shell at the end, as in the sample below:



oracle:x:50004:10003::/export/home/oracle:/bin/csh



where the shell is csh.



4. Get into the oracle shell.




Locate the shell in the "Output" column of the table in Step 2 above, then look up the entry in the "Environment File" column for the same row.



1. If you are using the C shell, enter the following command:




# source ~oracle/.cshrc



where oracle is your Oracle user, typically oracle.



2. If you are using the Korn shell or the Bourne shell, enter the following command:




# . ~oracle/your_environment_file



where oracle is your Oracle user, and your_environment_file is the name of your environment file.



5. Check the environment settings.




# env



The following sample output of this command lists the environment variables that must be set:




$ORACLE_HOME=$ORACLE_HOME from worksheet $ORACLE_SID=ECX $NLS_LANG=$NLS_LANG from worksheet $LD_LIBRARY_PATH=$ORACLE_HOME/lib:$LD_LIBRARY_PATH $PATH=$ORACLE_HOME/bin:$ORACLE_HOME:$PATH $DISPLAY=hostname:0.0 $TNS_ADMIN=$ORACLE_HOME/network/admin

6. Correct environment variable definitions as necessary.




If any of the above environment variables are not properly defined, do the following:



1. Log in as or change to your Oracle user, typically oracle . For example:




# su - oracle.



2. Open the environment file that you referenced in Step 4 above in a text editor and add or modify the definitions as necessary.



3. Save the environment file and exit the text editor.



7. Enable changes in environment variable definitions.




If you made changes in the environment file in Step 6 above, you can enable those changes now by switching to another user and then switching back to your Oracle user. For example:



# su - root
# su - oracle



Alternatively, you could restart your system and log in as your Oracle user.



8. Check your tnsnames.ora file.




Check your tnsnames.ora file to make sure it contains the correct information. The following are likely locations of your tnsnames.ora file:



• $ORACLE_HOME/network/admin



• /var/opt/oracle



• The directory specified by the $TNS_ADMIN environment variable



9. Connect to the database from the UNIX commandline:




# sqlplus ECX/ECX@your_connect_string



where ECX/ECX is the username/password of the ECXpert table-owner. If this test fails, skip to Step 11.



10. Repeat the test from inside SQL*Plus:




SQL> connect ECX/ECX@your_connect_string
SQL> exit



where ECX/ECX is the username/password of the ECXpert table-owner.



11. Correct any connectivity problems.




If the test at either Step 9 or Step 10 failed, check the tnsnames.ora and listener.ora file to validate the settings, such as hostname and SID.



After making any necessary changes, go back to Step 9 above.



If you have successfully connected to the database using SQL*Plus, you will be able to connect during the ECXpert migration.



If you cannot connect to the database using this method, you definitely will not be able to connect during the ECXpert migration.

Back Up Your Database

---

Note

The database backup is a major operation. You should plan carefully for both the disk space that will be required and the time slot in which the backup is executed. The backup will require as much disk space as the current database and the rollback tablespace in Oracle must be set to as much as 1.5 times the tablespace setting. The backup process can take 12 hours or more for a large database. Without proper planning, the process may abort part-way through. Refer to your Oracle documentation for additional guidelines and recommendations.

---

Follow the steps in this section to back up your existing ECXpert database.

1. Change to the $ACTRAHOME/Actra-apps/ECXpert/dbadmin/oracle directory.



2. Open the exp_ecx_tables.sh file in a text editor.



3. Change the character string name/password@dbAlias in the first line to be the username/password@dbAlias of your ECXpert table-owner user.



4. Enter the following command to run exp_ecx_tables.sh.




   # ./exp_ecx_tables.sh



If this command is successful, you should see output similar to the following, depending upon your currently installed version of Oracle with the ECXpert database:




(c) Copyright 1997 Oracle Corporation. All rights reserved.

Connected to: Oracle8 Release 8.0.4.0.0 - Production

PL/SQL Release 8.0.4.0.0 - Production

Export done in US7ASCII character set and US7ASCII NCHAR character set

About to export specified tables via Conventional Path ...

. . exporting table MEMBERS 10 rows exported

. . exporting table MBADDRESSES 15 rows exported

. . exporting table PARTNERSHIPS 3 rows exported

. . exporting table PNSTD 3 rows exported

. . exporting table PNGROUP 3 rows exported

. . exporting table KEYPAIRS 8 rows exported

. . exporting table CERTIFICATES 8 rows exported

. . exporting table TRACKING 1 rows exported

. . exporting table TRKINTCHG 0 rows exported

. . exporting table SERVICES 7 rows exported

. . exporting table MSGFORMATS 678 rows exported

. . exporting table EVENTLOG 0 rows exported

. . exporting table UNIQUEKEYS 19 rows exported

. . exporting table DTSERVICES 7 rows exported

. . exporting table SCHEDULEINFO 0 rows exported

. . exporting table TRKGROUP 0 rows exported

. . exporting table TRKDOC 0 rows exported

. . exporting table PNDOCS 3 rows exported

. . exporting table TRKDOCDETAILS 0 rows exported

. . exporting table CRL 0 rows exported

. . exporting table PNCARD 0 rows exported

. . exporting table MDNINFO 0 rows exported

. . exporting table BLOBINFO 8 rows exported

. . exporting table CERTTYPEINFO 5 rows exported

Export terminated successfully without warnings.

#

If instead you get the following error message:



./exp_ecx_tables.sh: Permission denied



enter the following command to set the proper permissions on the file:



# chmod 775 exp_ecx_tables.sh



and repeat this step.

Shut Down All ECXpert Services

If you are using a previous installation of the ECXpert Product Administrative Interface, you must log out and shut it down. Follow these steps to log out and shut down ECXpert.

1. Log out of the ECXpert Product Administrative Interface.




Click the Logout bar, then choose Applet > Quit if using the Applet Viewer.



2. Shut down all ECXpert services.




Display the ECXpert Main Menu in your browser as shown in Figure A-1 by entering the URL:



http://hostname:port#



where hostname is the name of your ECXpert host and port# is the port number it uses.

Figure A-1    ECXpert 3.0 Main Menu

Click the Admin button to display the ECXpert Server Administration menu shown in Figure A-2.

Figure A-2    ECXpert 3.0 Server Administration menu

If any ECXpert services are running, you will see more entries than the ECXpert Administration Server with an ON indication.

Click any service switch icon that is ON to toggle the service OFF and exit your browser window.

3. Shut down the iPlanet FastTrack Server or iPlanet (Netscape) Enterprise Server.




In an xterm window, enter the following commands, replacing machine_name with the name of your ECXpert host machine:



# cd $NSBASE/NS-apps/ns-home/http_prefix-machine_name
# ./stop







---

Note	In the above cd command, supply a value for http_prefix as follows: httpd for an unsecured Netscape FastTrack Server https for a secured Netscape FastTrack Server or Netscape Enterprise Server

---




4. Shut down the iPlanet Administration server.




In an xterm window, enter the following commands:



# cd $NSBASE/NS-apps/ns-home/
# ./stop-admin



5. Verify that no ECXpert processes are still running.




In an xterm window, enter the following command:



# ps -ef | grep actra



If additional processes are running, kill them manually.



6. If running SNMP, make sure the SNMP agent is shut down.




Manually kill the process ID for Program.o.

Preserve Your Files

Follow the steps in this section to back up the important files from your current ECXpert installation (ECXpert 3.0, 3.0 SP1, and/or 3.0 SP2):

1. Set up a temporary holding directory that is:



• outside both the current ECXpert version and any previous ECXpert Version directory trees.



• outside the /tmp directory



2. Copy the following files into your temporary holding directory:



• In all cases, from $NSBASE/NS-apps/ECXpert/config, copy the file ecx.ini.



• If your Netscape Enterprise Server is running secured, from
  $NSBASE/NS-apps/ns-home/httpd-machine_name/config, copy the files ServerCert.db, ServerCert.nm, ServerKey.db, magnus.conf, obj.conf, mime.types and any *.acl (access control list) files



• If using SNMP, copy the $NSBASE/NS-apps/ECXpert/SNMP/config/CONFIG file.



• Copy your maps and extra input card files from:
  - $NSBASE/NS-apps/ECXpert/maps/
- $NSBASE/NS-apps/ECXpert/data/input/



• Copy your live data—the following complete directories:
  - $NSBASE/NS-apps/ECXpert/data/work/trk
- $$NSBASE/NS-apps/ECXpert/data/output
- $NSBASE/NS-apps/ECXpert/data/bundle
- $NSBASE/NS-apps/ECXpert/smtp/inbound
- $NSBASE/NS-apps/ECXpert/smtp/outbound

Upgrade to Current ECXpert

Perform the steps in this section to upgrade to current ECXpert.

1. Begin to install the current ECXpert version, as described in ECXpert Getting Started, Chapter 2 "Installing ECXpert."




After the command-line-based installation completes, a browser appears with the browser-based installation steps.



2. Proceed normally through the screens for Installer Step One to Step Four, including Step Four.




Refer to Running the ECXpert Installer for detailed instructions. Be sure to stop when you reach "ECXpert Installer Step Five."



At this point, pause and run the migration script as described next.



3. In an xterm window, go to the directory containing the migration script.




Enter the following command:



# cd $NSBASE/NS-apps/ECXpert/dbadmin/oracle/migration/30_to_35



where $NSBASE is the directory under which you are installing current ECXpert.



4. Run the migration script.








---

Note	When entering the following command, do not add a trailing slash character (/) after the environment variables $ORACLE_HOME and ECX_3.5_HOME.

---




# ./migrate.pl -h $ORACLE_HOME -s ORACLE_SID -u User/Password[@TNS_alias] -w ECX_3.5_HOME



where:



• $ORACLE_HOME is the path to your Oracle home directory



• ORACLE_SID is your Oracle SID



• User is your Database User ID



• Password is your Database User password



• TNS_alias is the Oracle TNS alias for the ECXpert database (if Oracle is remote)



• ECX_3.5_HOME is the directory under which ECXpert is installed




For example:



# ./migrate.pl -h /disk1/oracle/wg816 -s ECX -u ECX1/ECX1 -w /disk1/Netscape/ns-apps/ECXpert



5. Return to the browser window and resume the browser-based installation at Step Five.








---

Note	You will return to the browser-based installation at step five but do not execute Step Five or Step Six of the installation — skip these on-screen installation steps, as instructed in Step 8 and Step 9 which follow on this page.

---



6. Click Skip on Step Five of the browser-based installation.



7. Click Skip on Step Six of the browser-based installation.



8. Proceed normally through the screens for Installer Step Seven to Step Ten and complete the rest of the tasks in Chapter 2 "Installing ECXpert."



9. Restore configuration settings from the temporary holding directory for your previous installation.



1. If using SNMP, copy the entire CONFIG file back to the new
   $NSBASE/NS-apps/ECXpert/SNMP/config/ directory.



2. Open your previous version of the ecx.ini file and the newly installed ecx.ini in a text editor and manually update the newly installed file very carefully by copying the following items in from the old one:




   any [...] sections for user-defined comms in their entirety



   any other parameters, from any [...] sections, where the old settings differ from those in the newly installed file.







---

Note

Some parameter names have changed slightly in current ECXpert; the new names are similar enough that you should be able to recognize them easily from the old names; be sure to check for a name change and replace any old names with the new names in any parameters that you copy into your new ecx.ini file.

---










---

Caution

Always work very carefully when manually editing your ecx.ini file. What appear to be relatively small mistakes can, in this file, have a serious impact on system function and can result in extended time to troubleshoot and correct system problems. In particular, be aware of the following two restrictions: Never duplicate a section heading ([...]) within the ecx.ini file. Never duplicate a parameter assignment within a section.

---

Updating Stored Procedures for Billing Code Addition

---

The Partnership Info tab of the Support Administrative User Interface has an added field for billing code. This field has not caused a database schema change for ECXpert 3.5. However, there is a stored procedure change. Therefore, for an existing ECXpert 3.0 series installation, the following stored procedure will need to be reloaded: ora_pkgbody.sql.

The procedure is to update this stored procedure is as follows:

1. As the Oracle user, go to a terminal window and the following directory:




cd $ECX3.5_HOME/dbadmin/oracle



2. Run the sqlplus program as follows:




sqlplus myaccount/mypassword@myserver



3. Execute the following sql program to update the stored procedures:




sqlplus>@ora_pkgbody.sql

Removing the Previous Installation and Database Backup

---

If you have followed the recommendation to move the earlier ECXpert install directory to a temporary location, leave the archival copy of the previous installation and the Oracle database backup in place until you are certain that the new installation of current ECXpert is working properly.

When the new version of ECXpert has been in production mode for a week or more, you may safely delete the previous installation and the Oracle database backup.