Important: Make sure to back up your database and test the migration process in a testing environment that is identical to the production environment prior to performing any changes on production.

Generally, you will perform migration as follows:

Migrate the system database.
If you are changing the database version, check whether the database schema is compatible with the previous schema; for example, schema of MSSql Server 2012 uses sequences, which were not available in previous versions and the schema used a table instead (in this case, drop the table LSPS_SEQ and create the sequence LSPS_SEQ with create sequence LSPS_SEQ start with <VALUE> increment by 1000; <VALUE> is the value from the old LSPS_SEQ table).
Run an application server with the LSPS Application over the migrated database and check if the running model instances are in correct state.
If you need to adapt running model instances, use the Model Update feature.
Manually migrate your Modules.
If you have a customized Application User Interface:
1. Generate a new LSPS Application and apply to it the changes from your current application.
  
  Alternatively, consider the API changes in the new application and apply them to your application.
2. Make sure to update the main pom.xml file:
  - update the parent version
```
<parent>
  <groupId>com.whitestein.lsps</groupId>
  <artifactId>lsps</artifactId>
  <version>3.1.1027</version>
</parent>
```
  - update the lsps version
```
<properties>
  <lsps.version>3.1.1027</lsps.version>
</properties>
```
    If you want to update the main pom.xml file from PDS, go to File > Open File, navigate to the root directory of the application and select file.
3. Rebuild the application.

In case you experience problems in any of the steps, make sure to remedy the situation before proceeding to the next step.

Migrating Modules from 2.7

In version 2.7, queries and like could have used the _ and % wildcards. To migrate your queries and like expressions change _ to ? and % to *.

If you want to retain the behavior set the COMPATIBILITY_VERSION column V_2_7. For example
UPDATE LSPS_MODULES SET COMPATIBILITY_VERSION = 'V_2_7' WHERE ID = 24000
and restart the server.

Important: Note that the mode is applied only in queries with the metadata nonStrictEscape.

Migrating Modules from 3.0

Modules created in LSPS 3.0 might require manual migration due to the following changes:

Characters in the name of modules and resources not allowed

Do not use the characters # / ? : \ * " < > | in the names of modules and resources (LSPS-7746)
Standard Library task types reflection records added

Task types of the Standard Library now generate their Activity records that have the same name as the task type. Make sure that names of records and tasks in your modules do not clash with these Activity record names (LSPS-7732).
Instantiation of processes with Activities with no incoming Flows

Previously, if a process contained several Activities without incoming Flows, the system instantiated a process for each Activity and each instance passed a token to one of the Activities with no incoming Flows. Now such a process is instantiated once and tokens are passed to all Activities with no incoming Flow at once (LSPS-7653).
Non-interruptible Boundary Cancel Intermediate Event removed

Boundary Cancel Intermediate Events are no longer interruptible. If a Process contains such an event, redesign the Process so that it uses the Boundary Cancel Intermediate Events as interruptible (LSPS-7580).
UIComponent no longer extends the Vaadin component

Since UIComponent no longer extends the Vaadin component, you need to migrate all Java custom components by removing the fireUIEvent() method and implementing the function "public AbstractComponent getWidget() { return this; }" (LSPS-7350).
JSF Application User Interface and Process Management Console removed

The JSF versions of Application User Interface and Process Management Console have been removed. Only Vaadin versions are now delivered and supported. All models that use form item based UI must be remodeled to UI Component based UI (LSPS-7097).

Database Migration

Important: Before running the script, make sure to back up your database and read the information on Migration on LSPS Forum.

To migrate the LSPS database to a newer version, do the following:

If your LSPS database contains the LSPS_SCHEMA_VERSION table, run the migration script with the databaseUrl and databaseType parameter: the script will migrate your current database to the database version required by the new Runtime Suite.
~/lsps-runtime/db-migration$ ./migrate.sh databaseUrl:jdbc:h2:tcp://localhost/h2/h2 user:eko password:mypasswd\$\'\`\"
Otherwise you need to do the following:
1. Get information on your current database version: open <YOUR_OLD_RUNTIME_SUITE>/db-migration/lsps-db-migration-<VERSION>.jar> db > migration:
  - Check the most recent java migration class in the location, for example, V3_1_0_010__Upgrade.class
  - 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).
2. Run the migration script located in the db-migration directory in <YOUR_NEW_LSPS_RUNTIME_SUITE> with the initialVersion parameter set to the current version of the LSPS database:
  
  First database migration with the user eko and password mypasswd$'`"
  ~/lsps-runtime/db-migration$ ./migrate.sh databaseUrl:jdbc:h2:tcp://localhost/h2/h2 user:eko password:mypasswd\$\'\`\" initialVersion:3.1.0.010

Migrate Script Parameters

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

databaseUrl*

URI of the database with LSPS runtime data

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.

When running the DB migration tool 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.