The focus on this release upgrades is the automatic database upgrade mechanism. As you already read in the release notes we use Flyway under the hood to provide this functionality. The second bigger change is that the edoras vis models are now saved in edoras gear and does not use any separate tables anymore and therefore the configuration of edoras vis changed and needs to be adapted. The last upgrades for this version deals with the unicode support and the enhanced large string value support.

Please stop the edoras one server, do all the upgrades described in the next paragraphs and then start the server again at the end. This way you ensure that all upgrades are executed properly and that you do not get an inconsistent state when starting it in the middle of the upgrades.

Migrate to the automatic database upgrade mechanism

Till now you needed to upgrade the database manually and this was not convenient and that is why we invested time to make it as easy as possible to upgrade to a newer version. This is a huge change in the underlying persistence logic and therefore the upgrade to that mechanism is cumbersome and needs to be done manually. But after that step these kind of upgrades are done automatically.

You maybe ask yourself why you need to do that manually, but the problem is that we need to establish a common baseline on all databases where edoras one is installed such that we are able to set this baseline to version 1.0.0 of the database. After that each database upgrade will increment the version of the database and hence we exactly know in which state the database is. For that we now need to synchronize the edoras one baseline database script with your database.

Before doing this step please ensure that you read all previous upgrade notes of older versions of edoras one and executed the needed database scripts. After that please open up the following file:

/com/edorasware/commons/core/persistence/schema/{DATABASE_TYPE}/edoras-gear_1.0.0_Initial_schema.sql (1)
1 Replace the {DATABASE_TYPE} placeholder with the database you use. Here the list of supported databases: db2, derby, h2, hsql, mssql, mysql, oracle, postgresql

You find the above mentioned file in the edoras-commons-core-3.0.2.S67-B35.jar library inside the WAR file or in your dependencies if you use edoras one as dependency.

Now you need to execute all the scripts on your database (ensure that you use the proper database user which has the rights to create/alter tables and that the user which reads them has the rights to read the new tables). You will get a lot of errors (and that is ok ;)) as some tables already exist and some will be created. After that ensure that all statements are created properly and that all tables are present in your database which are defined inside the edoras-gear_1.0.0_Initial_schema.sql file.

When you ensured the consistency between the upgrade script and your database please execute the create-baseline.sql file which is located in the same directory as the edoras-gear_1.0.0_Initial_schema.sql file. This database script creates the schema version table and sets the current state as baseline for the future database upgrades.

Please ensure that your database has the same structure with all needed fields and its types as in the edoras-gear_1.0.0_Initial_schema.sql file. This is a really important step and maybe check it twice to be really sure. If there is a mistake or a typo, then we cannot assure that the future database upgrades run through and this would result in an inconsistent database state, which is always hard to recover from.

These are all the steps needed to migrate to the automatic database upgrade mechanism.

Configuration changes of the edoras vis persistence

These changes are dependent on how you use edoras one: if you use the vanilla edoras-one-hosted WAR file then you do not need to follow these steps, but if you use edoras one as a dependency in your project then please read the changes carefully. Maybe not all changes apply to your setup as you did not overwrite the specified edoras one configuration files. These are the changes you need to do if you overwrite on of the mentioned files:

  1. In the com/edorasware/vis/config/vis-application-context.xml:

    1. remove the saveNotificationUrl property from the bean declaration with the id editorConfiguration.

    2. add a new bean declaration with the id edorasOneWorkspaceService and the class com.edorasware.one.service .EdorasOneWorkspaceService.

    3. add a new bean declaration with the id modelPersistence and the class com.edorasware.bpm.modeler.persistence.model.ModelPersistence.

  2. In the config/execution/work-object-management-config.xml remove the action-listener element with class com.edorasware.cloud.core.models.AppModelSynchronizationListener from the bean declaration with the id workObjectManagement.

  3. In the com/edorasware/cloud/core/config/base/work-object-management-config.xml add a new bean declaration with the id modelPersistenceService and the class com.edorasware .cloud.core.service.model.EdorasOneModelPersistenceService.

  4. In the com/edorasware/cloud/core/config/model-config.xml remove the bean declaration with the id cloudModelerSynchronizer.

After you adapted all the above configuration changes we need to clean up the database as we now store the edoras vis models inside edoras gear. When edoras one starts it migrates all edoras vis models from the specific tables to edoras gear. Please execute the following step after you finished all the upgrades in these upgrade notes, started edoras one and did a first smoke test of the system:

  1. Create a dump of the following database tables and then delete them from the database:

    1. EDW_BMO_MODEL

    2. EDW_BMO_MODEL_REVISION

    3. EDW_BMO_WORKSPACE

After these upgrades the part of changing the configuration of the edoras vis persistence is done.

Alter database table fields to support unicode

As already noted in the release notes, if you need unicode support for edoras one then please execute the following statements for your database. If your database is not listed then it already supports unicode by default.

Microsoft SQL Server

ALTER TABLE EDW_GEAR_WRK_OBJ ALTER COLUMN WRK_OBJ_NAME NVARCHAR(256);
ALTER TABLE EDW_GEAR_WRK_OBJ ALTER COLUMN WRK_OBJ_DESCRIPTION NVARCHAR(4000);

ALTER TABLE EDW_GEAR_WRK_VAR ALTER COLUMN WRK_VAR_NAME NVARCHAR(256);
ALTER TABLE EDW_GEAR_WRK_VAR ALTER COLUMN WRK_VAR_STRING_VALUE NVARCHAR(4000);

ALTER TABLE EDW_GEAR_WRK_OBJ_DEF ALTER COLUMN WRK_OBJ_DEF_NAME NVARCHAR(256);
ALTER TABLE EDW_GEAR_WRK_OBJ_DEF ALTER COLUMN WRK_OBJ_DEF_DESCRIPTION NVARCHAR(4000);

ALTER TABLE EDW_GEAR_WRK_PROP ALTER COLUMN WRK_PROP_NAME NVARCHAR(256);
ALTER TABLE EDW_GEAR_WRK_PROP ALTER COLUMN WRK_PROP_STRING_VALUE NVARCHAR(4000);

ALTER TABLE EDW_GEAR_BEAT ALTER COLUMN BEAT_NAME NVARCHAR(256);
ALTER TABLE EDW_GEAR_BEAT ALTER COLUMN BEAT_DESCRIPTION NVARCHAR(4000);
ALTER TABLE EDW_GEAR_BEAT ALTER COLUMN BEAT_SRC_OLD_VALUE_STRING NVARCHAR(4000);
ALTER TABLE EDW_GEAR_BEAT ALTER COLUMN BEAT_SRC_NEW_VALUE_STRING NVARCHAR(4000);

ALTER TABLE EDW_GEAR_BEAT_VAR ALTER COLUMN BEAT_VAR_NAME NVARCHAR(256);
ALTER TABLE EDW_GEAR_BEAT ALTER COLUMN BEAT_VAR_STRING_VALUE NVARCHAR(4000);

ALTER TABLE EDW_GEAR_DOM_OBJ ALTER COLUMN DOM_OBJ_NAME NVARCHAR(256);
ALTER TABLE EDW_GEAR_DOM_OBJ ALTER COLUMN DOM_OBJ_DESCRIPTION NVARCHAR(4000);

ALTER TABLE EDW_GEAR_DOM_VAR ALTER COLUMN DOM_VAR_NAME NVARCHAR(256);
ALTER TABLE EDW_GEAR_DOM_VAR ALTER COLUMN DOM_VAR_STRING_VALUE NVARCHAR(4000);

ALTER TABLE EDW_GEAR_DOM_OBJ_DEF ALTER COLUMN DOM_OBJ_DEF_NAME NVARCHAR(256);
ALTER TABLE EDW_GEAR_DOM_OBJ_DEF ALTER COLUMN DOM_OBJ_DEF_DESCRIPTION NVARCHAR(4000);

ALTER TABLE EDW_GEAR_DOM_PROP ALTER COLUMN DOM_PROP_NAME NVARCHAR(256);
ALTER TABLE EDW_GEAR_DOM_PROP ALTER COLUMN DOM_PROP_STRING_VALUE NVARCHAR(4000);

MySQL

For MySQL you need to change the connection string to the database and add the following two parameters:

  1. useUnicode=true

  2. characterEncoding=utf-8

Such that the JDBC URL looks like the following: jdbc:mysql://localhost:3306/edorasone?useUnicode=true&characterEncoding=utf-8.

Oracle

ALTER TABLE EDW_GEAR_WRK_OBJ MODIFY( WRK_OBJ_NAME NVARCHAR2(256) );
ALTER TABLE EDW_GEAR_WRK_OBJ MODIFY( WRK_OBJ_DESCRIPTION NVARCHAR2(4000) );

ALTER TABLE EDW_GEAR_WRK_VAR MODIFY( WRK_VAR_NAME NVARCHAR2(256) );
ALTER TABLE EDW_GEAR_WRK_VAR MODIFY( WRK_VAR_STRING_VALUE NVARCHAR2(4000) );

ALTER TABLE EDW_GEAR_WRK_OBJ_DEF MODIFY( WRK_OBJ_DEF_NAME NVARCHAR2(256) );
ALTER TABLE EDW_GEAR_WRK_OBJ_DEF MODIFY( WRK_OBJ_DEF_DESCRIPTION NVARCHAR2(4000) );

ALTER TABLE EDW_GEAR_WRK_PROP MODIFY( WRK_PROP_NAME NVARCHAR2(256) );
ALTER TABLE EDW_GEAR_WRK_PROP MODIFY( WRK_PROP_STRING_VALUE NVARCHAR2(4000) );

ALTER TABLE EDW_GEAR_BEAT MODIFY( BEAT_NAME NVARCHAR2(256) );
ALTER TABLE EDW_GEAR_BEAT MODIFY( BEAT_DESCRIPTION NVARCHAR2(4000) );
ALTER TABLE EDW_GEAR_BEAT MODIFY( BEAT_SRC_OLD_VALUE_STRING NVARCHAR2(4000) );
ALTER TABLE EDW_GEAR_BEAT MODIFY( BEAT_SRC_NEW_VALUE_STRING NVARCHAR2(4000) );

ALTER TABLE EDW_GEAR_BEAT_VAR MODIFY( BEAT_VAR_NAME NVARCHAR2(256) );
ALTER TABLE EDW_GEAR_BEAT_VAR MODIFY( BEAT_VAR_STRING_VALUE NVARCHAR2(4000) );

ALTER TABLE EDW_GEAR_DOM_OBJ MODIFY( DOM_OBJ_NAME NVARCHAR2(256) );
ALTER TABLE EDW_GEAR_DOM_OBJ MODIFY( DOM_OBJ_DESCRIPTION NVARCHAR2(4000) );

ALTER TABLE EDW_GEAR_DOM_VAR MODIFY( DOM_VAR_NAME NVARCHAR2(256) );
ALTER TABLE EDW_GEAR_DOM_VAR MODIFY( DOM_VAR_STRING_VALUE NVARCHAR2(4000) );

ALTER TABLE EDW_GEAR_DOM_OBJ_DEF MODIFY( DOM_OBJ_DEF_NAME NVARCHAR2(256) );
ALTER TABLE EDW_GEAR_DOM_OBJ_DEF MODIFY( DOM_OBJ_DEF_DESCRIPTION NVARCHAR2(4000) );

ALTER TABLE EDW_GEAR_DOM_PROP MODIFY( DOM_PROP_NAME NVARCHAR2(256) );
ALTER TABLE EDW_GEAR_DOM_PROP MODIFY( DOM_PROP_STRING_VALUE NVARCHAR2(4000) );

Alter database table fields to support the large string value

On some databases the old database scripts did not use the maximum available space for the fields. The following statements change the field type such that you are able to use the full available space for the specified fields. If your database is not listed then it already uses the proper type.

DB2

ALTER TABLE EDW_GEAR_WRK_VAR ALTER COLUMN WRK_VAR_LARGE_STRING_VALUE SET DATA TYPE CLOB;

ALTER TABLE EDW_GEAR_WRK_PROP ALTER COLUMN WRK_PROP_LARGE_STRING_VALUE SET DATA TYPE CLOB;

ALTER TABLE EDW_GEAR_BEAT_VAR ALTER COLUMN BEAT_VAR_LARGE_STRING_VALUE SET DATA TYPE CLOB;

ALTER TABLE EDW_GEAR_DOM_VAR ALTER COLUMN DOM_VAR_LARGE_STRING_VALUE SET DATA TYPE CLOB;

ALTER TABLE EDW_GEAR_DOM_PROP ALTER COLUMN DOM_PROP_LARGE_STRING_VALUE SET DATA TYPE CLOB;

Derby

ALTER TABLE EDW_GEAR_WRK_VAR ALTER COLUMN WRK_VAR_LARGE_STRING_VALUE SET DATA TYPE CLOB;

ALTER TABLE EDW_GEAR_WRK_PROP ALTER COLUMN WRK_PROP_LARGE_STRING_VALUE SET DATA TYPE CLOB;

ALTER TABLE EDW_GEAR_BEAT_VAR ALTER COLUMN BEAT_VAR_LARGE_STRING_VALUE SET DATA TYPE CLOB;

ALTER TABLE EDW_GEAR_DOM_VAR ALTER COLUMN DOM_VAR_LARGE_STRING_VALUE SET DATA TYPE CLOB;

ALTER TABLE EDW_GEAR_DOM_PROP ALTER COLUMN DOM_PROP_LARGE_STRING_VALUE SET DATA TYPE CLOB;

H2

ALTER TABLE EDW_GEAR_WRK_VAR ALTER COLUMN WRK_VAR_LARGE_STRING_VALUE CLOB;

ALTER TABLE EDW_GEAR_WRK_PROP ALTER COLUMN WRK_PROP_LARGE_STRING_VALUE CLOB;

ALTER TABLE EDW_GEAR_BEAT_VAR ALTER COLUMN BEAT_VAR_LARGE_STRING_VALUE CLOB;

ALTER TABLE EDW_GEAR_DOM_VAR ALTER COLUMN DOM_VAR_LARGE_STRING_VALUE CLOB;

ALTER TABLE EDW_GEAR_DOM_PROP ALTER COLUMN DOM_PROP_LARGE_STRING_VALUE CLOB;

HSQL

ALTER TABLE EDW_GEAR_WRK_VAR ALTER COLUMN WRK_VAR_LARGE_STRING_VALUE LONGVARCHAR;

ALTER TABLE EDW_GEAR_WRK_PROP ALTER COLUMN WRK_PROP_LARGE_STRING_VALUE LONGVARCHAR;

ALTER TABLE EDW_GEAR_BEAT_VAR ALTER COLUMN BEAT_VAR_LARGE_STRING_VALUE LONGVARCHAR;

ALTER TABLE EDW_GEAR_DOM_VAR ALTER COLUMN DOM_VAR_LARGE_STRING_VALUE LONGVARCHAR;

ALTER TABLE EDW_GEAR_DOM_PROP ALTER COLUMN DOM_PROP_LARGE_STRING_VALUE LONGVARCHAR;

Microsoft SQL Server

ALTER TABLE EDW_GEAR_WRK_VAR ALTER COLUMN WRK_VAR_LARGE_STRING_VALUE NVARCHAR(MAX);

ALTER TABLE EDW_GEAR_WRK_PROP ALTER COLUMN WRK_PROP_LARGE_STRING_VALUE NVARCHAR(MAX);

ALTER TABLE EDW_GEAR_BEAT_VAR ALTER COLUMN BEAT_VAR_LARGE_STRING_VALUE NVARCHAR(MAX);

ALTER TABLE EDW_GEAR_DOM_VAR ALTER COLUMN DOM_VAR_LARGE_STRING_VALUE NVARCHAR(MAX);

ALTER TABLE EDW_GEAR_DOM_PROP ALTER COLUMN DOM_PROP_LARGE_STRING_VALUE NVARCHAR(MAX);

Miscellaneous

Removal of patch related classes

As we upgraded to the automatic database upgrades we also refactored how the data upgrades are executed. We now use Flyway to execute these data upgrades such that we know when they were executed and in which state the database is. Therefore we could remove some old classes which we used in the old upgrade service. The following changes has been done:

  1. Inside the com.edorasware.cloud.core.init.OneInitializer we removed the preInitializers as we do not need them anymore.

  2. Inside the com.edorasware.cloud.core.patch.PatchService we removed the patchListeners as we do not need them anymore.

  3. We also removed the com.edorasware.cloud.core.patch.PatchListener class.

If you still need a callback which needs to be executed before the data upgrades are executed you are able to implement a org.springframework.context.SmartLifecycle bean which returns a phase (org.springframework.context.SmartLifecycle#getPhase()) smaller than the phase of the com.edorasware.cloud.core.init.config.OneInitializationPhase.ONE_INITIALIZATION_PHASE.