LSPS documentation logo
LSPS Documentation
Updating

When deploying new artifacts, regardless of whether you are upgrading the entire LSPS stack, your modules, make sure that the version of the LSPS system database corresponds to the LSPS version your application and modules are created in: If you migrated the LSPS system database to a particular version of LSPS, then your modules and potentially your business database schema with your data should be migrated to the same version.

The resources for the migration should be provided along with the updated application EAR or modules. For information on the resources, refer to developer documentation.

Uploading Updated Modules

Required artifacts:

  • zip files with modules and models
  • optionally, model update definition files
  • optionally, database schema script

To update modules on your LSPS Server:

  1. Terminate or suspend running model instances.
  2. If applicable, migrate the business database schema.
  3. Upload new models with the database update strategy set to Do nothing with database schema, Update the schema by model, or Validate schema first. If you have migrated the database in the previous step, set the strategy to Do nothing with database schema.
  4. If applicable, update the suspended model instances.

    Important: Model update can be very complex. Prepare the model update resources beforehand and test it properly.

  5. 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:

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

Migrating the LSPS System Database Tables

When upgrading your LSPS application, you will need to upgrade the LSPS system database.

Important: 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, run the migration script:

  • 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 of the Runtime Suite.
    ~/lsps-runtime/db-migration$ ./migrate.sh databaseUrl:jdbc:h2:tcp://localhost/./h2/h2 user:eko password:mypasswd\$\'\`\"
  • Otherwise, find the schema version in the migration tool:

    1. Get current database version: open <YOUR_OLD_RUNTIME_SUITE>/db-migration/lsps-db-migration-<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).

    2. Run the migration script 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

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, ./migrate.sh databaseType:SQLSERVER databaseUrl:jdbc:sqlserver://localhost/lsps;instance=whitestein.

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.