Migrating from ENOVIA V5 VPM V5R19 to ENOVIA V5 VPM V5R20 in UNIX

Special Notes

R20 GA utility Upgrade520_Enovia.sh will support migration of standard and customized LCA Unix Oracle and DB2 databases for AIX, HP, and Solaris in Oracle and DB2. A separate program (Upgrade520NT_Enovia.sh) supports migration of databases from R19 to R20 on Windows Server.

Scope & Purpose

This documentation allows a user to migrate an existing ENOVIA V5 VPM V5R19 database into a database containing structures and data that will support ENOVIA V5 VPM V5R20 while maintaining all the user-supplied data that was generated during use of the product under ENOVIA V5 VPM V5R19.

A database migrated through this process will be converted from R19 to R20. The migration process does NOT create a separate copy of the database, but instead converts the existing database. Once you have performed this migration, you cannot use ENOVIA V5 VPM R19 on this database without dropping it and restoring a backup image of the database that was taken while it was still in R19. Attempting to run ENOVIA V5 VPM V5R19 on the database after it has been migrated to R20 is unsupported.

Assumptions

These instructions assume you are migrating directly from V5R19 to V5R20. This procedure does not support any other releases or migration effort. Do not attempt to use any other releases of ENOVIA V5 VPM with these instructions.

These instructions also assume you have a working V5R19 installation, including a completely functional Oracle or DB2 database that is up and running before beginning migration. Oracle or DB2 software should be at a level supported in the ENOVIA V5 VPM installation documentation for R20. There should be no users connected to ENOVIA V5 VPM or the database at the time of migration.

Overview

The R19 > R20 migration is done in 7 steps that each perform a particular unit of work on the database. The steps listed below generate their own unique output log that contains the name of the step embedded in the file name, located in the directory specified by the -TMP parameter. Thus, if a step fails for some reason, we can look at the logs that pertain directly to that step to determine the cause of the failure.

Before the official migration steps begin, we do some introductory environmental preparation and checking the database availability by connecting to it successfully. Then we use a function called GETMETAR20LIST, which gets the list of all the Metadata that is used in R20. This is a hard coded list that was obtained from a CD-install of R20 by connecting to its database and doing select schemaname from rdbentitymapping and then eliminating VPMAdminSchema from the list. This step does not change anything during migration, it simply loads the values of some variables that will be needed later.

Then we proceed to the steps of migration as follows:

• DDL - This step is required. Uses R19 and R20 metadata to generate database scripts (DDL) necessary to make the database structure changes to convert to R20 and then executes the DDL to make the changes.
  
  Output= Upgrade520.logGENERATEDDL, Upgrade520.logRUNGENDDL, Upgrade520.logCustoProcessDDLSetup, Upgrade520.logCustoProcessDDL
• ADMIN - This step is required. Runs AddCustoInAdmin (in a customized environment) and LoadAdmin (in all environments). These make changes to the database based on the contents of the VPMAdmin.adm file. The ADMIN step has a dependency on the DDL step. You cannot run the ADMIN step without simultaneously running the DDL step during a migration. If you put DDL on the EXCLUSIONLIST, the ADMIN step running alone will fail. You must run them both together during the same execution of the migration script.
  
  Output = Upgrade520.logADMIN
•  MASKS - This step is required. Updates P&O (People & Organizations) data (users, contexts and roles) and default masks.
  
  Output = Upgrade520.logMASKS
• STATS - This step is optional. Runs “update statistics” (DB2) or “analyze statistics” (Oracle) on all the ENOVIA V5 VPM tables in the database to improve performance of the ENOVIA V5 VPM product in the future.
  
  Output = Upgrade520.logSTATS
• GRAPH - This step is required. Updates the default status graphs.
  
  Output = Upgrade520.logGRAPH
• VEXT -  This step is required. This updates the VEXTENSION attribute value of the Documents by running utility called as ENOVMigDOCVExtension.
  After running this utility over the existing databases, the truncated old extensions “CATAnalysisResul” and “CATAnalysisCompu” will be replaced with complete extensions as “CATAnalysisResults” and “CATAnalysisComputations” respectively.
  
  Output = Upgrade520.logVEXT
• PUB - This step is required/available for DB2 Database only. Changes attributes from “LONG VARCHAR” to “VARCHAR”.
  
  Output = Upgrade520.logPUB
• LVCHAR - This step is required/available for DB2 Database only. Changes attributes from “LONG VARCHAR” to “VARCHAR”.
  
  Output = Upgrade520.logLVCHAR
   

Before You Begin

1. VERY IMPORTANT: Before starting the migration, make an offline (cold) backup of your R19 database in the current Oracle or DB2 database environment and copy it off to tape or other offline storage device.
2. Ensure that you are migrating directly from V5R19 to V5R20. These procedures do not support any other releases or migration effort. Do not attempt to use any other releases of ENOVIA LCA with these instructions.
3. Ensure that you have a working V5R20 installation, including a completely functional Oracle or DB2 database that is up and running before beginning migration.
   1. Oracle or DB2 software should be at the level required in the documentation for ENOVIA V5 VPM in R20
4. There should be no users connected to ENOVIA LCA or the database at the time of migration.
5. VERY IMPORTANT: Ensure that you have large transaction logging capability in the database. DDL steps will fail if they run out of logging during the extensive updates needed for successful migration. Add transaction logs (DB2) or more tablespace to the rollback segments (Oracle) as needed. The size needed depends on the size of your database. We recommend you increase the logging space normally taken by your database by 100% before starting migration, and more may be required depending on your environment. Consult DB2 or Oracle documentation for instructions on how to make these changes and how to undo them after migration, if desired.
6. If you are using DB2, ensure that the STMTHEAP parameter value on your database is set to at least 3500. You can check this by logging in as the database administrator ID and running:
   
   db2 get db cfg for <databasename> | grep STMT
   
   If it is < 3500, increase it by using the following commands:
   
   db2 update db cfg for <databasename> using STMTHEAP 3500;db2stop force;
db2start
   
   Consult DB2 documentation for more details about this parameter and how to modify it.
7. If you are using DB2, ensure that the APPLHEAPSZ parameter for your database is set to at least 1000 and your LOCKLIST is set to at least 4000 and MAXLOCKS is set to 40. Check this by logging in as the database administrator and running:
   
   db2 get db cfg for <databasename> | grep APPLHEAPSZ
db2 get db cfg for <databasename> | grep LOCKLIST
db2 get db cfg for <databasename> | grep MAXLOCKS
   
   To increase it:
   
   db2 update db cfg for <databasename> using APPLHEAPSZ 1000 LOCKLIST 4000 MAXLOCKS 40;
db2stop force; db2start
8. If using DB2, ensure that STAT_HEAP_SZ database configuration parameter is set to at least 9000 during the duration of the 19 > 20 migration. To increase it:
   
   db2 update db cfg for <databasename> using STAT_HEAP_SZ 9000
db2stop force; db2start
   
   Consult DB2 documentation for more details about these parameters and how to modify them.
9. If you have created your own Masks, you should save the Mask information (the old version of the Default Mask + your own Mask) prior to starting the migration. Refer to CAA-RADE R20 documentation: Migrating Existing ENOVIA Masks / Retrieving Needed Masks for Merging.
10. IF YOU HAVE CUSTOMIZED security processes (from the customized modeler) in People & Organization: There are some special steps you need to take if you want to preserve these customizations and migrate them into R20. If you do not take these steps, your basic P&O functionality will work, but the customizations you added in R19 will be lost.
    1. Exclude the MASKS step from the 19->20 database migration. See the information elsewhere in this document on how to put MASKS on the EXCLUSIONLIST so that it is not executed during the migration.
    2. Before migration begins, while the product is still active in R19, export P&O data using the following commands:
       1. cd $INSTALL_PATH/xxx_a/code/command <-- referring to the installation path and the aix_a, hp_a, solaris_a directory where the product is installed
       2. ./catstart -run "VPMPeopleImport -export /savepath/PeopleExportFile"
          - >  where "/savepath" is a path where your data will be saved and can be protected
          from deletion or alteration until migration is completed.
    3. After migration is finished (with the MASKS step excluded), migrate your existing customization using CAA RADE. See the documentation of CAA-RADE R20 "Migrating an Existing Customization" for complete information. Be sure to include your customized security processes in these updates.
    Before Migration Begins: Ensure that you have a good EnvName.txt file in your Install-Path/xxx_a directory. For example, if your install path is /usr/DS/R19, you will have a path under this directory with the name of your operating system (like aix or hp or solaris) in it. Inside this directory, there should be a file named EnvName.txt that contains the name of the ENOVIA V5 VPM level you are using. For example, the text inside the file will look something like this:
    
    ENOVIA_V5_VPM.V5R20.B20
    
    Ensure that this file exists in both R19 and R20, that it is named EnvName.txt, and that it contains the correct name for the ENOVIA V5 VPM environment that you are migrating at both levels.
11. Install ENOVIA V5 VPM R20 pointing to existing ENOVIA V5 VPM V5R19 database
    Follow the CD installation steps for ENOVIA V5 VPM V5R20 with the following special instructions:
    1. Use the same database vendor as ENOVIA V5 VPM V5R19 used.
    2. Use the same database name and path as ENOVIA V5 VPM V5R19.
    3. Set the new vault to the same Unix path as the ENOVIA V5 VPM V5R19 vault.

    Use a different Port Number for ENOVIA V5 VPM V5R20 than ENOVIA V5 VPM V5R19 used. Do not select the Database objects nor the Startup Data options - this is because we will be using the existing database and data from R19. You may have to unselect these 2 options if they are selected by default.
    After your installation (PLMDBSetup) is completed, you must manually change the information in the properties file to set the V5R20 Vault to the same path as the old V5R19 Vault.
    
    To do this:

    • cd to the Java Properties directory ~/<platform>_a/docs/java (platform = aix, hpux, solaris)
    • edit the ENOVIAVaultServer.properties file

    If you have defined your own Vault(s) - other than the one created during product installation - you must recreate in V5R20 the additional vault(s) using the directions contained in the section "Setting Up the Vault Server Manually" after migration is completed. Make the same Java Properties changes to document these additional vaults as well.

    There is no Vault Database migration from R19 to R20 because there are no vault database changes. However, you still must perform the steps to configure your R20 vault database to point to the R19 vault files. Important: You must perform this R20 vault configuration and activate the R20 vault (pointing to the R19 database and R20 vault files paths) before starting the migration utility documented here. If you do not activate the R20 vault, the IWTQ step of this migration may fail.

12. Set the V5MEM environment variable in the .txt file in your CATEnv directory to 8:
    
V5MEM=8

Migration Steps

Migrate ENOVIA V5 VPM V5R19  >  ENOVIA V5 VPM V5R20

1. Logon to the ENOVIA LCA server with the ENOVIA administrator ID. DO NOT attempt to run the migration as root. DO NOT login as root and su to the ENOVIA administrator id. Open a separate window by logging in as the ENOVIA admin ID. Keep the root window you used in STEP 1 available also.
2. cd to the code/command directory under your ENOVIA LCA product install path. This path appears like one of the following:
   ~/aix_a/code/command
~/solaris_a/code/command
~/hpux_b/code/command
   under the directory where you installed the product.
3. Create (for example, using the vi editor) a command file containing all the parameters you will need to run the migration script. The parameters should all wrap continuously as one line; there should be no carriage return.
4. The command line for CUSTOMIZED option is as follows: (If you are running STANDARD migration, skip ahead to Step 5 and DO NOT run Step 4.) A Customized database is one that is used in an environment that has been altered using customizations produced by the RADE tool.
   
   ./catstart -run -s “Upgrade520_Enovia.sh ... “
   
   The info below goes into the “…” of the command line. Be sure to put the double quotes (“) around the command from the beginning of Upgrade520_Enovia.sh to the end of the last parameter.

Here are two sample executable files with working command lines for CUSTO migration, one for Oracle and one for DB2:

DB2

./catstart -run -s "Upgrade520_Enovia.sh -DBVendor DB2 -DBName DBNAME1 -DBAdmHome /home/db2adm -TbsName ENOTBS -IdxTbsName ENOTBS -Tbs32KName ENOTBS32 -IdxTbs32KName ENOTBS32K -TableOwner EV5ADM -AdmUsr ev5adm -DBAID db2adm -EnvDir /mig/R19/CATEnv -EnvName ENOVIA_V5_VPM.V5R20.B20 -R19path /mig/R19/aix_a/code/dictionary/ -R19custo /R19custo/aix_a/code/dictionary/ -R19CustoWorkspace /R19custo/aix_a/reffiles/DBMS/Generator/ -TMP /tmp/output -Step ALL”

ORACLE

./catstart -run -s “./Upgrade520_Enovia.sh -DBVendor ORACLE -DBName ORADB1 -DBAdmHome /home/oracle/9.2.0 -TbsName ENOTBS -IdxTbsName ENOTBS -Tbs32KName ENOTBS32 -IdxTbs32KName ENOTBS32K -TableOwner EV5ADM -AdmUsr ev5adm -DBAID ev5adm -EnvDir /path/R19/CATEnv -EnvName ENOVIA_V5_VPM.V5R20.B20 -R18path /path/R19/aix_a/code/dictionary -R19custo /path/R19custo/aix_a/code/dictionary/
-R19CustoWorkspace /path/R19custo/aix_a/reffiles/DBMS/Generator/ -TMP /usr/out -Step ALL“
 

5. The command line for STANDARD option is as follows: (If you are running CUSTOMIZED migration, go back to Step 4 and DO NOT run Step 5.)
   
   ./catstart -run -s “Upgrade520_Enovia.sh ... “ The info below goes into the “…” of the command line. Be sure to put the double quotes (“) around the command from the beginning of Upgrade520_Enovia.sh to the end of the last parameter.

The R20 migration has the capability to run all the steps except the ones that you would like to exclude. You might want to do this if:

• You do not want to run one of the optional steps
• You have experienced a problem on some steps but the others have already succeeded. Rather than run the entire migration again, you can correct the problem and then run with all the succeeded steps excluded.

To run all the steps except for one or more to be excluded, follow these procedures:

1. Create a text file called EXCLUSIONLIST (all capital letters) under the directory provided in your -TMP parameter.
2. List the steps inside this file that you DO NOT want to be executed during the migration.
   
   For example, you might create a file /tmp/EXCLUSIONLIST that looks like this:
   
   STATS
3. Now run the migration with the -Step ALL parameter. It will run all the steps except the ones you mentioned in the EXCLUSIONLIST.
4. Notice that Step names are all capital letters and are all listed in bold type in the OVERVIEW section of this document above.
5. It is not permitted to run the ADMIN step without running the DDL step simultaneously, due to dependencies inside ADMIN.

Recognize that some steps have dependencies on the successful completion of other steps. If you try to run any individual step out of order or without completion of its dependencies, the migration script will stop and report that a dependency has been violated and will advise you what to do.

6. chmod 700 (filename) ...where (filename) is the parameter file you created in the steps above. You must also run the command: export PATH=$PATH:. <- to include current directory in your path.
7. Run the (filename) script from the Unix command line. Informational status messages appear. Some steps will take several minutes, during which no additional messages will appear.
8. If you did not specify the DBAID password on the command line, a prompt will appear as follows:
   
   Enter password for Database Admin Id (xxxxxx):
    
   --where xxxxxx is the userid that you put into your command line as the Database Administrator. Type in the password for this userid. It will not be displayed on the screen.
9. If you did not specify the ENOVIA Admin User password on the command line, a prompt will appear as follows:
   
   Enter password for EV5 Admin User (XXXXXX):
   
   --where XXXXXXX is the userid that you put into your command line as the ENOVIA Administrator. Type in the password for this userid. It will not be displayed on the screen.
10. If running with the -Step ALL parameter, the failure of any critical steps will abort the script and the other steps will not run. Optional steps may allow the migration to continue if they fail. If a step fails:
    • resolve the error and then rerun any steps that did not execute or that failed the first time, in the order that they appear in the STATUS message at the end of the failed execution (also documented in the OVERVIEW above). This allows you to keep the results of any steps that succeeded, but requires you to manually run each step for the rest of the migration until they are all completed or use the -Step ALL with the EXCLUSIONLIST.
    • or restore the database and run again with the -Step ALL parameter after resolving the error. This wipes out all migration done so far and completely starts over.
11. Be patient. Migration of a large database can take several hours. If the migration appears to be hung, you can verify progress by opening a second window and going to the directory you gave as your TMP directory. Use the command ls -lst and look at the timestamp on the most recent Upgrade520* file. If more than 1 hour passes with no activity in this directory, it is likely the migration has stopped.
12. If you used something other than CAARADE to customize your ENOVIA V5 VPM R19 environment, and you have customized a schema, you now need to consult with the author or maintainer of those customizations to obtain instructions for migrating these customizations into ENOVIA LCA R20.
13. If you have not already done so, don’t forget to reconfigure your Vault in R20 to point to the R19 Vault. You must follow the procedures documented in the "Migrating a Vault Server Manually" section.

Special Notes on Migration of Lifecycles (Graphs)

If you want to remove a lifecycle state for an object type, you should either:

• ensure that no objects of this type exist in that state, or
• leave the state in the lifecycle graph, with an appropriate transition to a state in the new lifecycle. In this case, users can migrate the old data to the new lifecycle states as needed.

You may update the lifecycle either by editing the text of the lifecycle VGraph file, or by editing the lifecycle in the ENOVIA VPM Product Editor, then exporting to a VGraph file and adding any specialized conditions and operations.

If necessary, you may retrieve the old customized lifecycle VGraph from the old ENOVIA database, but you must do this before you migrate the ENOVIA database to the new release.