This document describes the steps needed to upgrade the edoras one application to 1.5.0.S117.
Please stop the edoras one server, perform all upgrade steps described below and then restart the server again at the end.
App and model support
This release includes a major refactoring of the edoras one app and model support. The key changes are:
-
model references in models and deployed definitions now use one of the following two values:
-
the model global ID
-
the model key (stored in the model’s 'key' variable)
-
-
the following references have been replaced by the global ID:
-
the model work object ID
-
the model ID (stored in the model’s 'guid' variable)
-
the constant for the 'guid' variable (
CloudVariables.MODEL_ID
) has been moved to the new classLegacyConstants
-
-
the exported app archive structure has been updated with the following changes:
-
the modelMetadata.xml file has been removed
-
redundant copies of the model revisions have been removed (an app contains only the latest revision)
-
some edoras vis models contain a revision ID placeholder instead of the exported revision ID
-
-
newly-created models no longer have a 'guid' variable
-
a lot of internal model handling code and services have been changed to:
-
use
GlobalId
instead ofWorkObjectId
-
use
WorkObject<?, ?, ?>
instead ofAnyWorkObject
-
use
GenericWorkObjectService
instead ofAnyWorkObjectService
-
In most cases no specific upgrade action needs to be taken: existing models and definitions in the edoras one database will be migrated automatically on system startup and apps exported by previous releases will be migrated automatically to the new structure on import. In addition, edoras one REST endpoints will continue to support the model work object ID for now.
Changes may be required in an edoras one project if:
-
classes from the core edoras one product have been overwritten (especially where these classes access models or definitions)
-
model services or helper classes are used in the solution code
-
model references are stored somewhere outside of the edoras one system
Due to the large scope of the changes in the product, it is not possible to provide a detailed description of all affected classes in the product. If you think that your project has been affected by this change and you require more information please context edorasware support.
Validating the upgrade
The data checks needed to validate the model references after the upgrade are fairly time-consuming and therefore it is not possible to perform this data check as part of the normal system startup. The full data consistency check can still be performed on-demand once the application has started by doing the following:
-
log into edoras one as the system administrator
-
open the page
rest/api/v1/maintenance/dataCheck
(relative to your edoras one root URL)
No output will be shown in the browser but the full data consistency check will be started in the background and the results will appear in the server log.
Process task preview
In some cases you may notice that the preview for a process task uses the fallback preview image:
instead of the correct preview based on the modeler’s own process diagram:
This can be resolved by opening affected process models in the modeler, saving them, and then redeploying any apps that were updated. New process instances will then have the correct preview image.
Updated GenericWorkObjectService interface
The following changes have been made to the GenericWorkObjectService
. In most cases the existing interface is
supported without changes, but there are some interface changes that will result in compilation errors in application code.
If you have some compilation errors after upgrading then the following information should allow these to be fixed. The changes
needed in each case are all minor.
ID-based methods
The GenericWorkObjectService
interface provides methods for accessing work objects based on the
work object global ID value. Combining this interface with code that is uses the work object ID
means that it is necessary to perform frequent conversions between ID and global ID values, e.g.:
GlobalId caseGlobalId = this.genericWorkObjectService.getGlobalId(caseId); WorkObject<?, ?, ?> result = this.genericWorkObjectService.findWorkObject(caseGlobalId);
In this release, convenience methods have been provided to allow GenericWorkObjectService
method calls to use work object IDs directly, removing the need for explicit ID conversion in the
application code:
WorkObject<?, ?, ?> result = this.genericWorkObjectService.findWorkObject(caseId);
the restriction that GenericWorkObjectService can only be used within a tenant scope
still applies even for the ID-based methods.
|
addWorkObject changes
To support the use case where no parent is required, a new variant of the addWorkObject
method is now provided
without a parent work object ID parameter. In addition, the addWorkObject
methods now return the complete persisted
work object rather than just the global ID:
AnyWorkObject workObject = AnyWorkObject.builder().name("Test").build(); AnyWorkObject newWorkObject = this.genericWorkObjectService.addWorkObject(workObject, "test");
This avoids the need to explicitly fetch the work object again after it has been added. If you don’t need the
full work object you can just call getGlobalId()
on the returned work object to get the original behaviour.
startEntity changes
Variants of the startEntity
method are now provided that do not require additional variable parameters
or a parent work object ID to be supplied, simplifying code for those cases where this information is not
required. In addition, variable information is now supplied exclusively using the VariableMap
data structure.
The previous variants of the startEntity
method (e.g. taking name/value pairs or maps) are now supported by
using the relevant VariableMap
builder methods:
this.genericWorkObjectService.startEntity(processDefinitionId, VariableMap.of("test", "foo"));
ID lookup caching
As part of the improvements to the GenericWorkObjectService
implementation, the edoras one cache configuration
was extended to cache the results from work object ID lookup method calls. The caches are configured in the Spring
configuration file cache-config.xml
with the following advice IDs:
-
edorasGear-globalIdById
-
edorasGear-idByGlobalId
If you are overwriting the cache configurations in your project then you should make sure that these caches are correctly configured. No cluster-based caching is required for these caches as the work object IDs are immutable and can be cached separately on each node.
Bootstrap project
Here you will find a list of files which have changed in the bootstrap project since the last release. This helps you check the difference between your bootstrap project version and the current one:
-
src/test/java/com/edorasware/acme/expression/AcmeServiceIntegrationTest.java
-
test refactoring because of
AbstractBaseTest
changes -
edoras-one-documentation/src/edoras-one-bootstrap/src/main/java/com/edorasware/acme/expression/AcmeService.java
-
Changing package reference after GenericWorkObjectService refactoring