When upgrading the LSPS application, your modules, or modules of a library, make sure that the version of the LSPS system database corresponds to the LSPS version used by your updated application and modules.

If you migrate the LSPS system database to a newer version of LSPS and use the new PDS to adapt shared Records and their relationships in your modules, you need to migrate your database tables as well, typically with a flyway script.

Consider distributing resources for your database-table migration with the updated application EAR and modules. For information on the resources, refer to developer documentation.

Important: Before performing any updates, back up your database.

Updating Modules

Once you have created and tested a new version of your module, you need to plan how to update it:

If your new model is changing its shared records or their relationships, you need to prepare scripts that will migrate the existing database data to the new database schema.
If you changed the workflow, update will depend on whether your model are restartable or not:
- When updating restartable models, the restartability of models is the result of the model design. To re-design existing models to be restartable might require significant effort depending on the model complexity. Consider reading about the basic idea behind the restartability pattern and to the agile processes for its more advanced version.
- For other models, prepare the model update configuration and follow the instructions for updating with module update configurations.

Required artifacts:

zip files with modules and models
optionally, model update definition files or the model restart orchestration model
optionally, database schema script

Updating Modules with Restartable Processes

If you are using the restartable processes pattern in your modules do the following: To update modules on your LSPS Server:

Terminate or suspend running model instances.
If applicable, run your scripts that migrate your business database tables.
Upload new models with the database update strategy of the upload configuration set to Do not change, Update by model, or Validate. If you have migrated the database in the previous step, set the strategy to Do not change.

In production environments, the Do not change stategy is recommended.
Run the orchestration process to start the relevant model instances.
Inspect the status of model-instances starting in the Application Restart view in the Management perspective or in Management Console.

Updating Modules with Model Update

If you are using the model update feature to recover the status of your model instances, do the following: To update modules on your LSPS Server:

Terminate or suspend running model instances.
If applicable, run your scripts that migrate your business database tables.
Upload new models with the database update strategy of the upload configuration set to Do not change, Update by model, or Validate. If you have migrated the database in the previous step, set the strategy to Do not change.

In production environments, the Do not change stategy is recommended.
If applicable, update the suspended model instances.

Important: Model update can be very complex: make sure to prepare the model update resources beforehand and test the entire update process properly.
Continue the suspended model instances.

Updating the LSPS Application

Required artifacts:

LSPS Application EAR

Provided the new LSPS Application has been created in the same minor version of PDS, for example 3.3, it is enough to deploy the new LSPS Application EAR to the application server. Otherwise, refer to Upgrading LSPS.

Upgrading LSPS

Required artifacts:

LSPS Application EAR
zip files with modules and models exported with GO-BPMN export
optionally, model update definition files
optionally, database schema script for business data when applicable

When upgrading your LSPS, you will need to upgrade the entire stack:

LSPS system database: Mind that the database holds the LSPS system data and possibly your business data based on the LSPS data type models.
LSPS Application: apart from updating the EAR, you might need to upgrade also the version of your database and application server.
Models and modules: even if you have not introduced changes to your models, you need to at least upgrade the standard library modules they use and make sure you models work with them correctly.

Important: Make sure to test the upgrade in a testing environment that is identical to the production environment and back up your database before you perform any changes on production.

To upgrade to a newer LSPS version, do the following:

Make sure the environment meets the requirements of LSPS.
Suspend any running model instances.
Stop the application server.
Migrate the LSPS system database.
Deploy the EAR file to your LSPS server (refer to instructions on how to set up a server for LSPS.
Upload updated modules and update their instances.
Migrate business data.
Start the server.

Migrating LSPS System Database Tables

When upgrading your LSPS application, you need to upgrade the LSPS system database. Make sure to back up the database and test the migration process in a testing environment that is identical to the production environment before you perform any changes on production.

To upgrade the LSPS system database to correspond to a newer LSPS version, do the following:

Migrate the LSPS system tables:

If your LSPS database contains the LSPS_SCHEMA_VERSION table, run the migration script with the databaseUrl and databaseType parameter: the script migrates your current database to the database version of the Runtime Suite.
```
~/lsps-runtime/cli-tools$ java -jar lsps-db-migration-lsps-<VER>-full.jar \
--databaseUrl jdbc:h2:tcp://localhost/./h2/h2 --user lsps --password lsps
```

Otherwise, find the schema version in the migration tool:

Get the current database version: open <YOUR_OLD_LSPS_TOOLS_PACKAGE>/cli-tools/lsps-db-migration-lsps-<VERSION>.jar> db > migration:
1. Check the most recent java migration class in the location, for example, V3_1_0_010__Upgrade.class
2. Open the directory of your database, for example mysql and check the latest SQL script, for example, MYSQL_V3_1_0_003__Upgrade.sql
Your current version is the higher version (in the example case, it is 3.1.0.010).

Run the migration script with the initialVersion parameter set to the current version of the LSPS database:

~/lsps-runtime/cli-tools$ java -jar \
lsps-db-migration-lsps-<VERSION>-full.jar --databaseUrl \
jdbc:h2:tcp://localhost/./h2/h2 --user lsps --password lsps \
--initialVersion 3.1.0.010

~/lsps-runtime/cli-tools$ java -jar \
lsps-db-migration-lsps-<VERSION>-full.jar --databaseUrl \
"jdbc:sqlserver://localhost:1433;databaseName=lsps;sendStringParametersAsUnicode=false" \
--user lsps --password lsps

~/lsps-runtime/cli-tools$ java -jar \
lsps-db-migration-lsps-<VERSION>-full.jar --databaseUrl \
jdbc:oracle:thin:@localhost:1521:lsps --user lsps --password lsps

~/lsps-runtime/cli-tools$ java -jar \
lsps-db-migration-lsps-<VERSION>-full.jar --databaseUrl \
jdbc:db2://localhost:50000/lsps --user admin --password admin

If you are using the LSPS BAM library, migrate the BAM tables:

~/lsps-runtime/cli-tools$ java -jar \
lsps-db-migration-bam-<VERSION>-full.jar --databaseUrl \
jdbc:h2:tcp://localhost/./h2/h2 --user lsps --password lsps

When running the DB migration from the command line, make sure to escape any special characters in parameter values as required by your operating system or shell. For example, if using Bash and a parameter contains characters like $ ` ' " and so on then these characters must be escaped: Read the manual to your command line to learn how to escape special characters.

Important: The migration of LSPS tables will fail while executing V3_3_2_004_Delete_user_guest.sql with an error similar to the following:
SQL State  : 23000Error Code : 547Message    : The DELETE statement conflicted with the REFERENCE...
This happens if you have assigned a security role or a model role to the guest user: This user has been removed due to security reasons. Please, remove such roles from the user prior to migration. If you require the user, re-create it after the migration.

Parameters of the Database Migration Tool

The database migration script accepts the following parameters with the respective value entered after a colon:

databaseUrl*

URI of the database with LSPS runtime data

Note: For SQL databases, the instance property is supported: add the instance to the url as instance=<name>, for example,
~/lsps-runtime/cli-tools$ java -jar lsps-db-migration-lsps-<VERSION>-full.jar \
--databaseUrl "jdbc:sqlserver://localhost/lsps;instance=wt" \
--user lsps --password lsps

databaseType

type of the database (The migration tool attempts to identify the database type automatically from the databaseUrl parameter. However, if necessary, you can define the database type explicitly. The possible values are H2, DB2, ORACLE, SQLSERVER, MYSQL.

initialVersion

The current version of LSPS database: it corresponds to the LSPS that created the database. The parameter is required if the database is being migrated for the first time: On the first migration, the underlying tooling creates a database table with information on the previous and current schema version. Next migrations use this data to identify the initial database version so that the parameter is no longer required.

targetVersion

The parameter is optional. If undefined, the database is migrated to the Runtime Suite database version.

flyway

The flyway command to execute over the database, such as, info, clean (cleans the entire LSPS database including any business or library tables, such as BAM tables), validate, migrate, and repair (repairs hash codes of migration scripts in case these were modified).

~/lsps-runtime/cli-tools$ java -jar lsps-db-migration-lsps-<VERSION>-full.jar \
--databaseUrl "jdbc:sqlserver://localhost:1433/lsps;instance=wt" \
--user lsps --password lsps --flyway info