CU Exchange Up to S 39.5.12

Description of versions < S 39.5.12

Requirements

• On the system on which the CU exchange is performed (usually the application server),
  • Java must be installed (JDK/JRE at least in version 1.7 or later), and
  • the environment variable JAVA_HOME containing the path of the Java installation must be set,
  • Pentaho PDI (Kettle) must be available (at least version 4.1.3),
  • the environment variable KETTLE_DIR that contains the path to the Pentaho directory must be set.
• Source and target system, including the changeset number (hotfix), must be on the same level.
• All new DIs that have been created in the source database, must be created in the destination database as well. Ignoring this rule upon CU exchange leads to a crash.
• Regarding module variants
  • If module variants from the Q3B schema are to be considered in the CU exchange from a development system (source) to a test/training or productive system (destination), the following must be ensured upfront in order to avoid conflicts (this is not solved by the CU exchange itself):
    • The automatic numbers of the module variants (DT500) and I-numbers/texts (DT544) in the Q3B schema in both systems must stem from different number ranges in order to avoid conflicts.
      • Tip: Set the prefix of the automatic numbers of DT500 and DT544 to Customer license + 1 in the development system
        • Here, it is required that the data in the corresponding tables are on the same level.
        • This is only the case in the beginning, when the source is set up anew as a copy of the destination or after an interim CU exchange.
        • Since this setting is transferred from source to destination upon CU exchange as well, a script which subsequently resets both automatic number prefixes to the default value in the destination system is additionally required (see inactive/epilogue folder).
          • If module variants deviate from one another between destination and development system without these measures, the Q3B files must not be transferred.
            • In this case, and also if you generally want to renounce the transfer of module variants, the corresponding lines (table entries DT500, DT501, DT502, DT503, DT545) are to be deleted from the list of tables to be transferred before CU unload (unloading of data from the development system) (see data table list), or, if unloading is already completed, the table files from the unloads folder are to be deleted as well.

Details

• The CU exchange is available in any appropriate Migration subdirectory in the working system.
• The Migration folder contains, among other things, at least the following folders and files which are required for the CU exchange:

File/folder	Meaning
common	contains commonly used components
conf	Configuration folder, contains, a.o., the update.conf configuration file with the corresponding CU exchange parameters to be modified (s.u.)
CUunload	contains the procedure for unloading the data from the source
CUexchange Prologue Epilogue Inactive	contains the procedure for exchanging the data in the destination Subfolder for creating customized SQL scripts to be run before the CU exchange Subfolder for creating customized SQL scripts to be run after the CU exchange Subfolder for creating and collecting customized SQL scripts that are currently not run
log	The log directory in which log files are stored, which is written upon unloading and exchange
setVar.bat setVar.sh	Script for setting the JAVA_HOME environment variables (Path to the Java JDK or JRE installation) and KETTLE_DIR (Path to the Pentaho PDI/Kettle directory) (Windows/Linux)
CUunload.bat CUunload.sh	Start script for unloading the source data (Windows/Linux)
CUexchange.bat CUexchange.sh	Start script for exchanging the CU data in the destination (Windows/Linux)

Settings

Information

• The CU exchange can be configured via the update.conf parameter file in the conf subdirectory.
• For the CU exchange, the following prameters are relevant and must be adjusted accordingly:

Parameter	Value
planta.update.license	three digit customer license (e.g. 123); in case you want more than one license to be active, they must be specified separated by commas (e.g. 123,456)
planta.unload.data_dir	Path, below which the source data are stored
planta.cu_exchange.type	Type of the CU exchange Possible values: ALL = must be set in the development to productive system constellation, for the Q1B/Q2B schemas are exchanged completely STANDARD = must be set in case of a final CU exchange at the end of a customer system migration. Here, only the records belonging to the standard are exchanged, the records with customer license remain untouched
planta.db.source.type	Source DBMS Possible values: MSSQL ORACLE POSTGRESQL
planta.db.source.access	Source DBMS Possible values: Native ODBC
planta.db.source.name	Source DB name (in Oracle the SID)
planta.db.source.host	Source server (on which the DBMS resides)
planta.db.source.user	Source DB user
planta.db.source.pass	Source DB user password
planta.db.source.port	Usually one of the following values if not set differntly: 1521 (Oracle) 1433 (MSSQL) 5432 (PostgreSQL)
planta.db.destination.type	destination DBMS Possible values: MSSQL ORACLE POSTGRESQL
planta.db.destination.access	destination DBMS Possible values: Native ODBC
planta.db.destination.name	destination DB name (in Oracle the SID)
planta.db.destination.host	Source server (on which the DBMS resides)
planta.db.destination.user	destination DB user
planta.db.destination.pass	destination DB user password
planta.db.destination.port	Usually one of the following values if not set differntly: 1521 (Oracle) 1433 (MSSQL) 5432 (PostgreSQL)

Process flow

Information

• A Cu exchange takes about two hours

To do

• Customer
  • Make sure that no users are in the destination environment anymore.
  • Backup of the destination and source database
  • Acceptance after successful Cu exchange
• PLANTA
  • Preparing the CU exchange:
  • Stop server
  • Unload the destination and source environment
  • Load to the destination environment
  • Start server
  • Test
  • Approve for acceptance by the customer's technical project manager

Process flow

Process step	Person responsible
Information on the planned maintenance work to user groups	customer's technical project manager
Make sure that non of the customer's employees works on the system anymore	operation
Backup of the productive DB	Operation
Unload of the customizing files from the test and productive environment	PLANTA
Load into the productive environment	PLANTA
Testing the night jobs	PLANTA
Approval	by PLANTA to the customer's technical project manager
Acceptance	by the customer's technical project manager

Detailed procedure

Procedure

• Open a command line window and switch to the migration folder.
• Make sure that the requirements are met (especially that environment variables are set).
• Check/set the parameters of the configuration file (~conf/update.conf) . In case no data connection can be established later, check the connection parameters here considering that depending on the infrastructure, other port numbers than the standard port numbers are be used.

CU unload

• Depending on your system, open CUunload.bat (Windows) or Cuunload.sh (Linux).
  • As a result, the customizing of the source system is stored under the path specified in the planta.unload.data_dir parameter.
• Check whether the script output has been carried out successfully.
  • In the log subdirectory, the CUunload.txt protocol file allows a more specific check.

CU exchange

• Before the exchange, no user may have the system running anymore.
• Once this is ensured, stop the PLANTA application server of the destination system.
• Carry out a backup of the database or the user.
• Check the CUexchange/Prologue and Epilogue directories.
  • Here, customized SQL batch scripts, which are to be carried out before (prologue) or after (epilogue) the CU exchange can be stored.
  • In the source system, e.g., changes to the schema, can be replicated for the destination system by storing the appropriate DDL scripts in Prologue.
  • In Epilogue, scripts for setting the update date after completed exchange and resetting the automatic number template for module variants can be stored and I-texts
  • for the scripts used for the destination system can be moved to Inactive.
    • Especially scripts for schema changes are usually to be carried out once only and upon frequent use of the CU exchange, they must be deleted from Epilogue after execution.
• Depending on your system, open CUexchange.bat (Windows) or CUexchange.sh (Linux).
  • As a result, the destination system customizing is replaced by the data from the planta.unload.data_dir path.
• Check whether the script output has been carried out successfully.
  • In the log subdirectory, the CUunload.txt protocol file allows a more specific check.
• Make sure that server and client are on the same version
  • A changed customizing usually contains changed Python scripts as well (on part of the server and/or client). Therefore, you may have to replace the Python Python directories of the destination system as well.
• Start the PLANTA application server of the destination system.

Data Tables

Note

• The following data tables, that are mainly tables of the Q1B and Q2B schemas (as well as the tables connected to module variants from Q3B) are exchanged upon CU exchange (list from ~/conf/CUtables.txt):
  • DT030
  • DT031
  • DT032
  • DT033
  • DT035
  • DT036
  • DT037
  • DT055
  • DT316
  • DT320
  • DT321
  • DT333
  • DT339
  • DT340
  • DT341
  • DT342
  • DT343
  • DT346
  • DT348
  • DT349
  • DT354
  • DT390
  • DT391
  • DT392
  • DT395
  • DT396
  • DT397
  • DT404
  • DT405
  • DT406
  • DT407
  • DT408
  • DT409
  • DT410
  • DT411
  • DT412
  • DT414
  • DT415
  • DT416
  • DT417
  • DT419
  • DT420
  • DT421
  • DT424
  • DT425
  • DT428
  • DT429
  • DT432
  • DT433
  • DT434
  • DT435
  • DT439
  • DT440
  • DT441
  • DT444
  • DT445
  • DT447
  • DT449
  • DT452
  • DT453
  • DT454
  • DT456
  • DT458
  • DT500
  • DT501
  • DT502
  • DT503
  • DT510
  • DT512
  • DT513
  • DT514
  • DT515
  • DT519
  • DT520
  • DT521
  • DT522
  • DT545