Migration notes 5.1

This page explains the changes required to migrate to the stated version of Atoti Sign-Off.

Migrate to 5.1.0

Upgrading from version 5.0.0 See Atoti Sign-Off 5.1.0 Release Notes.

Atoti Sign-Off is using Atoti Server 6.0.9 and Atoti UI 5.1.x, and the Signoff-ext module 2.1.0.

For new features and fixes included in these releases, please see:

Headline announcement

  • Java 17 upgrade : Atoti Sign-Off is now compatible with, and requires, Java 17.
  • Atoti Server upgrade : Atoti Sign-Off has been upgraded to Atoti Server 6.0.9.
  • Spring Security upgrade : We have upgraded Spring Security to version 5.8.7 to resolve vulnerabilities and prepare for the upgrade to Spring Security 6.0 (via Spring Boot 3).
  • Removal of ActivePivotRemotingServicesConfig: The import of ActivePivotRemotingServicesConfig has been removed from the configuration class ActivePivotCoreConfig.

note

The security vulnerability mitigated is CVE-2016-1000027. It affects the httpinvoker package in Spring. By removing the remoting services, the vulnerable package is not utilized. A full fix will be provided when Atoti Sign-Off is upgraded to Spring 6.

  • Unique task definition names : Task definitions must now be created with a unique name. If a task definition is created with a name that already exists in the database, an error is thrown. Uniqueness is enforced at the point that a task definition is published. Existing task definitions are unaffected.
  • Common Parent POM : The Common Parent POM version 1.2.0 is now a parent of the Atoti Sign-Off module.
  • Common Dependencies BOM : The Common Dependencies BOM version 1.2.0 has been added to the list of dependencies of the module.
  • Solutions Tools BOM : The Solutions Tools BOM version 2.0-AS6.0 dependency is now used instead of the Accelerator Tools BOM version 1.0-AP6.0. All included tools are compatible with, and require Java 17.
  • Removal of ActiveMonitor import The import of the ActiveMonitor POM has been removed from the main POM file of the module and has been replaced by the import of the activepivot-server-spring POM and the activepivot-copper2-test dependency.
  • Removal of ActivePivotRemotingServicesConfig import: The optional ActivePivotRemotingServicesConfig remoting configuration import has been removed to mitigate a security vulnerability.
  • Re-applying adjustments: When an application server fails and restarts, previous adjustments are automatically applied for tasks that are not yet approved. Refer to the User Guide for more information.

Breaking changes

  • Upgrades
    • Atoti Sign-Off 5.1.0 is compatible with, and requires Java 17.
    • The Solutions Tools BOM version 2.0-AS6.0 dependency is now used instead of the Accelerator Tools BOM version 1.0-AP6.0. All included tools are compatible with, and require Java 17.
    • Because the Common Parent POM version 1.2.0 is present in the Maven groupId com.activeviam.apps, the Sign-Off module Maven artifacts are now present in the groupId com.activeviam.apps instead of com.activeviam.tools.
    • The Spring Security configuration has been upgraded to version 5.8.7, for future compatibility with Spring 6.0. Customizations built on previous versions will need to be migrated.
    • The sample workflows have been modified with additional tasks to handle application server failures. This is not a breaking change for running sign-off tasks, but may be a breaking change for any customizations made to these workflows.
    • The AdjustmentDiscardExecutionRetrievalService and AdjustmentDiscardExecutionTask classes have been deleted.
    • ApplicationProperties has been renamed to RestApiProperties, and it now has a private constructor. The getRestApis method, which added RestTemplates to the Spring Context has been removed. There is a getServers method that returns the same list of supported servers, but the creation of RestTemplates is now handled by the RestTemplateconfiguration class.
    • The IApplicationSignOff interface declares a new method: getApplicationStatus.
    • The ISignOffProcessInstanceWorkflowService interface declares a new method: notifyApplicationStatusChange.
    • The SignOffProcessDefinitionJpaService overrides the validateCreateEntity method from the AVersionedObjectJpaService parent class. This is to prevent creating definitions with duplicate names.

Java 17 upgrade

The Module is now built and intended to be run within a Java 17 JVM. Some functionality in the full application and in the regressions tests requires deep reflection access to Java packages. To enable access, please use the following JVM parameters, either through the command line or maven surefire/failsafe configuration.

--add-opens=java.base/java.util=ALL-UNNAMED

note

The Module will not work in a Java 11 JVM.

The following setup has been added to the configuration of the maven-surefire-plugin artifact in the main POM file and in the signoff-starter POM file:

<argLine>
  @{jacoco.agent.surefireArgLine}
  --add-opens=java.base/java.util=ALL-UNNAMED
</argLine>

Common Parent POM

The Common Parent POM version 1.2.0 is now a parent of Atoti Sign-Off. This parent merely defines plugin management and is used by other solutions. The following dependency versions are now managed by this parent instead of Atoti Sign-Off, and have been removed from the dependency management of the module:

Dependency Removed version Imported version
maven-source-plugin 3.2.1 3.3.0
maven-javadoc-plugin 3.2.0 3.5.0
maven-surefire-plugin 3.0.0-M5 3.1.2
maven-jar-plugin 3.2.0 3.3.0
maven-compiler-plugin 3.8.1 3.11.0
maven-dependency-plugin 3.1.2 3.6.0
maven-war-plugin 3.3.1 3.4.0
eclipse-m2e 1.0.0 1.0.0
jacoco-maven-plugin 0.8.9 0.8.10

Those dependencies have also had their explicit version declaration removed in the list of dependencies.

Because the Common Parent POM version 1.2.0 is present in the Maven groupId com.activeviam.apps, the Sign-Off module Maven artifacts are now present in the groupId com.activeviam.apps instead of com.activeviam.tools.

As a consequence, the following dependencies are now present in the groupId com.activeviam.apps instead of com.activeviam.tools:

Main POM file:

These dependencies changed: New dependencies:

<dependency>
    <groupId>com.activeviam.apps</groupId>
    <artifactId>workflow-core</artifactId>
    <version>${workflow-core.version}</version>
</dependency>
<dependency>
    <groupId>com.activeviam.apps</groupId>
    <artifactId>workflow-core</artifactId>
    <version>${workflow-core.version}</version>
    <classifier>tests</classifier>
</dependency>

Old dependencies:

<dependency>
    <groupId>com.activeviam.tools</groupId>
    <artifactId>workflow-core</artifactId>
    <version>${workflow-core.version}</version>
</dependency>
<dependency>
    <groupId>com.activeviam.tools</groupId>
    <artifactId>workflow-core</artifactId>
    <version>${workflow-core.version}</version>
    <classifier>tests</classifier>
</dependency>

signoff-activeviam POM:

These imports have changed: New imports:

<parent>
    <groupId>com.activeviam.apps</groupId>
    <artifactId>signoff</artifactId>
    <version>5.1.0</version>
</parent>

<dependency>
    <groupId>com.activeviam.apps</groupId>
    <artifactId>workflow-core</artifactId>
</dependency>

Old imports:

<parent>
    <groupId>com.activeviam.tools</groupId>
    <artifactId>signoff</artifactId>
    <version>5.0.0</version>
</parent>

<dependency>
    <groupId>com.activeviam.tools</groupId>
    <artifactId>workflow-core</artifactId>
</dependency>

signoff-starter POM:

These imports have changed: New imports:

<parent>
    <groupId>com.activeviam.apps</groupId>
    <artifactId>signoff</artifactId>
    <version>5.1.0</version>
</parent>

<dependency>
    <groupId>com.activeviam.apps</groupId>
    <artifactId>workflow-core</artifactId>
</dependency>

<dependency>
    <groupId>com.activeviam.apps</groupId>
    <artifactId>signoff-activeviam</artifactId>
    <version>${project.version}</version>
</dependency>

Old imports:

<parent>
    <groupId>com.activeviam.tools</groupId>
    <artifactId>signoff</artifactId>
    <version>5.0.0</version>
</parent>

<dependency>
    <groupId>com.activeviam.tools</groupId>
    <artifactId>workflow-core</artifactId>
</dependency>

<dependency>
    <groupId>com.activeviam.tools</groupId>
    <artifactId>signoff-activeviam</artifactId>
    <version>${project.version}</version>
</dependency>

Common Dependencies BOM

The module now imports third party dependency versions from the Common Dependencies BOM version 1.2.0. The following dependency has been added to the main POM file:

<dependency>
  <groupId>com.activeviam.apps</groupId>
  <artifactId>common-dependencies-bom</artifactId>
  <version>${common-dependencies-bom.version}</version>
  <type>pom</type>
  <scope>import</scope>
</dependency>

The following explicit dependency versions have been removed from the dependency management section of the module:

Dependency Removed version Imported version
springboot 2.7.2 2.7.16
logback-classic 1.2.3 1.2.12
commons-collections4 4.4 4.4
velocity-engine-core 2.2 2.3
velocity-tools-generic 3.0 3.1
commons-csv 1.8 1.10.0
commons-io 2.11.0 2.13.0
mockito-core 4.5.1 3.12.4
assertj-core 3.22.0 3.22.0
junit-bom 5.8.2 Not imported anymore
guava 29.0-jre Not imported anymore

Solutions Tools BOM

The Solutions Tools BOM version 2.0-AS6.0 dependency is now used instead of the Accelerator Tools BOM version 1.0-AP6.0.

In the maim POM file, the following dependency has been added:

<dependency>
    <groupId>com.activeviam.apps</groupId>
    <artifactId>solutions-tools-bom</artifactId>
    <version>${solutions-tools-bom.version}</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

and the following dependency has been rmoved:

<dependency>
    <groupId>com.activeviam.tools</groupId>
    <artifactId>accelerator-tools-bom</artifactId>
    <version>${accelerator-tools-bom.version}</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

As a consequence, the following dependency has changed in the signoff-activeviam POM and in the signoff-starter POM files:

New import:

<dependency>
    <groupId>com.activeviam.apps</groupId>
    <artifactId>datastore-helper</artifactId>
</dependency>

Old import:

<dependency>
    <groupId>com.activeviam.tools</groupId>
    <artifactId>datastore-helper</artifactId>
</dependency>

Removal of ActiveMonitor import

The following dependency has been removed from the main POM file:

<dependency>
    <groupId>com.activeviam.activemonitor</groupId>
    <artifactId>activemonitor</artifactId>
    <version>${activepivot.version}</version>
    <type>pom</type>
    <scope>import</scope>
    <exclusions>
        <exclusion>
            <groupId>org.activiti</groupId>
            <artifactId>activiti-spring</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.activiti</groupId>
            <artifactId>activiti-engine</artifactId>
        </exclusion>
    </exclusions>
</dependency>

The following dependency have been added to the main POM file:

<dependency>
    <groupId>com.activeviam.activepivot</groupId>
    <artifactId>activepivot-server-spring</artifactId>
    <version>${activepivot.version}</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>
<dependency>
    <groupId>com.activeviam.activepivot</groupId>
    <artifactId>activepivot-copper2-test</artifactId>
    <version>${activepivot.version}</version>
</dependency>

workflow-core POM

The workflow-core module has been upgraded to 6.0.9. The Common Parent POM version 1.2.0 is now a parent of the workflow-core module. Because the Common Parent POM version 1.2.0 is present in the Maven groupId com.activeviam.apps, the workflow-core artifacts are now present in the groupId com.activeviam.apps instead of com.activeviam.tools.

The workflow-core module now imports third party dependency versions from the Common Dependencies BOM version 1.2.0. The following dependency has been added to the workflow-core POM file:

<dependency>
  <groupId>com.activeviam.apps</groupId>
  <artifactId>common-dependencies-bom</artifactId>
  <version>${common-dependencies-bom.version}</version>
  <type>pom</type>
  <scope>import</scope>
</dependency>

The following explicit dependency versions have been removed from the dependency management section of the module:

Dependency Removed version Imported version
spring-core 5.3.23 5.3.30
spring-test 5.3.23 5.3.30
mockito-core 4.5.1 3.12.4
javax.servlet-api 4.0.1 4.0.1
h2 2.1.214 2.1.214
velocity-engine-core 2.2 2.3
velocity-tools-generic 3.0 3.1
commons-io 2.11.0 2.13.0
commons-csv 1.8 1.10.0
assertj-core 3.22.0 Not imported anymore
guava 29.0-jre Not imported anymore
validation-api 2.0.1.Final Not imported anymore

The following dependencies have been added to the workflow-core POM file:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

Spring Security upgrade

We have upgraded to Spring Security 5.8.7, which is a dependency of Atoti Server 6.0.9, using Spring’s migration guide.

You will eventually need to migrate your own custom security configuration(s) in preparation for Spring Security 6.0. We have upgraded our out-of-the-box security configurations to help in this migration.

note

We recommend using your own custom security configuration(s) and referring to the out-of-the-box security configuration provided only as a sample.

The default security users and roles have not changed, only the way we implement the security. We have done so by making the following changes:

Stop Using WebSecurityConfigurerAdapter

We have replaced instances of WebSecurityConfigurerAdapter with SecurityFilterChain beans.

Use the new requestMatchers methods

In Authorize Http Requests, we have replaced invocations of http.authorizeHttpRequests((authz) -> authz.antMatchers(...)) with http.authorizeHttpRequests((authz) -> authz.requestMatchers(...)).

Use the new securityMatchers methods

We have replaced invocations of http.antMatchers(...) with http.securityMatchers(...).

As an example of the previous changes, the configuration for accessing the endpoint which exposes the Atoti Server service describing deployed REST APIs changed from:

@Configuration
@Order(2)
// Must be done before ActivePivotSecurityConfigurer (because they match common URLs)
public static class VersionsSecurityConfigurer extends AWebSecurityConfigurer {

    @Override
    protected void doConfigure(HttpSecurity http) throws Exception {
      String url = "/versions";
      http
              .antMatcher(url + "/**").authorizeRequests()
              .antMatchers(url + "/**").permitAll()
              .and().httpBasic();
    }
}

to

@Bean
@Order(2)
@SneakyThrows
public SecurityFilterChain versionsSecurityFilterChain(HttpSecurity http) {
    return http
        .securityMatcher(url(VersionServicesConfig.REST_API_URL_PREFIX, WILDCARD))
        .authorizeHttpRequests(auth -> auth.anyRequest().permitAll())
        .build();
}

Removal of ActivePivotRemotingServicesConfig

The import of ActivePivotRemotingServicesConfig has been removed from the configuration class ActivePivotCoreConfig.

Configuration files

Files Modified

application.yml

New properties:

Property Name Comment Value
application.rest-api.MR.status-endpoint A rest endpoint that can be called to determine if the server is running. The endpoint should return HTTP status code 200 if running (MR). /activeviam/pivot/rest/v8/ping
application.rest-api.MR.polling-period-in-milliseconds The frequency with which application servers are polled to determine if they are running (MR). 5000
application.rest-api.MR.initial-delay-in-milliseconds The delay that should be applied from starting the sign-off server to beginning to poll application servers to determine if they are running (MR). 1000
application.rest-api.MR.notify-on-failure-count The number of times to observe that the application server has changed from a running state to a not running state before notifying sign-off tasks (MR). 3
application.rest-api.MR.notify-on-success-count The number of times to observe that the application server has changed from a not running state to a running state before notifying sign-off tasks (MR). 1
application.rest-api.FRTB.status-endpoint A rest endpoint that can be called to determine if the server is running. The endpoint should return HTTP status code 200 if running (FRTB). /activeviam/pivot/rest/v8/ping
application.rest-api.FRTB.polling-period-in-milliseconds The frequency with which application servers are polled to determine if they are running (FRTB). 5000
application.rest-api.FRTB.initial-delay-in-milliseconds The delay that should be applied from starting the sign-off server to beginning to poll application servers to determine if they are running (FRTB). 1000
application.rest-api.FRTB.notify-on-failure-count The number of times to observe that the application server has changed from a running state to a not running state before notifying sign-off tasks (FRTB). 3
application.rest-api.FRTB.notify-on-success-count The number of times to observe that the application server has changed from a not running state to a running state before notifying sign-off tasks (FRTB). 1

Configuration classes

Classes added

Class Name Comment
ApplicationStatusConfig Configures beans that poll application servers to determine when they have stopped/started running, and notify tasks to take appropriate action.
RestTemplateConfiguration Creates a Spring RestTemplate bean for each application server. Previously, these were created in the ApplicationProperties class.

Classes modified

Class Name Comment
ApplicationProperties Renamed to RestApiProperties, and new properties added. Also, now implements the IRestApiConfiguration interface.
SecurityConfig Added a serviceUserAuthentication bean. This is an authentication for the Sign-off server that allows it to transition tasks when an application server starts or stops.

Processes

Changed processes

Name Details
simple When the process is in the INITIATED state, it will now be transitioned to an AWAIT_SERVER_RESTART status when the relevant application server fails. When the server resumes it will be transitioned to a RE_APPLY_ADJUSTMENTS state where adjustments are automatically re-created, and then back to the INITIATED state.
four-eyes When the process is in the INITIATED or PENDING states, it will now be transitioned to an AWAIT_SERVER_RESTART status when the relevant application server fails. When the server resumes it will be transitioned to a RE_APPLY_ADJUSTMENTS state where adjustments are automatically re-created, and then back to the INITIATED state.
four-eyes-kpi When the process is in the INITIATED or PENDING states, it will now be transitioned to an AWAIT_SERVER_RESTART status when the relevant application server fails. When the server resumes it will be transitioned to a RE_APPLY_ADJUSTMENTS state where adjustments are automatically re-created, and then back to the INITIATED state.

Other changes

  • The following dependencies have been added to the signoff-starter POM file:
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
</dependency>

<!-- *** LOGGING: use Logback as concrete logging framework binding for SLF4J *** -->
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <scope>runtime</scope><!-- not needed for compilation -->
</dependency>
  • The SignOffProcessInstanceDTOWithExportStatus class has been removed. This was used as the return value of SignOffProcessInstanceWorkflowRestController.get, which now returns SignOffProcessInstanceDTO instead.
  • To improve type-safety, IExportStatusService.addExportStatusRequest/.addExportFailed now expects a SignOffProcessInstanceDTO parameter in place of a String for the task key.
  • To improve type-safety, the constructors for the ExportStatusTask class now expect a SignOffProcessInstanceDTO parameter in place of a String for the task key and one of the constructors now expects an ExportStatusWithTaskIdDTO in place of a String giving the reason for the export failure.
  • SignOffProcessInstanceDTO.getExportStatusDetails and WorkflowProcessInstanceDTO.getExportStatusDetails now return ExportStatusWithTaskIdDTO in place of a String, and this type must also be passed to the corresponding setter methods.

note

These DTOs are frequently populated with entities from the database. However, this change is backwards compatible, meaning existing database entities can be converted to the new DTOs without needing to carry out any migrations.

  • The AdjustmentDiscardExecutionRetrievalService and AdjustmentDiscardExecutionTask classes have been removed. These were used to poll the application servers when an adjustment was deleted. However, this was also carried out by the AdjustmentStatusTask and was therefore redundant.
  • The requestAdjustmentExecutionDeletion method in the SignOffAdjustmentExecutionService class now creates an AdjustmentStatusTask that polls the application server using the execution ID from the deletion request. Previously, this was using the execution ID from the initial adjustment request which may have led to incorrect statuses being returned.
  • ApplicationStatusService and ApplicationStatusTask classes have been added. When the Sign-off server starts, a task is created for each application server (MR, FRTB etc.). The tasks monitor the servers at specified intervals and indicate a status of UP or DOWN to any observing objects. Custom objects can be set to observe these status updates by creating the object as a Spring bean of type IObserver<ApplicationServerAndStatus>. The ProcessNotifyingApplicationStatusObserver is implemented out-of-the-box and uses these updates to notify sign-off tasks when changes occur.
  • The getApplicationStatus method has been added to the IApplicationSignOff interface and the corresponding ApplicationSignOffRestClient implementation. This can be used to determine if an application server is running or not.
  • The notifyApplicationStatusChange method has been added to the ISignOffProcessInstanceWorkflowService interface and the corresponding SignOffProcessInstanceWorkflowService implementation. This is used to notify sign-off tasks that an application server has started or stopped running by sending signals.
  • The executeInitiateAfterServerFailure method has been added to the SignOffProcessInstanceWorkflowService class. This corresponds to an Activiti service task with the implementation string signOffProcessInstanceInitiateAfterServerFailure and is executed by the sample workflows when an application server has failed and restarted. It re-initiates the sign-off task with the application server and re-applies any adjustments that previously existed.
  • An executeRecurringAdjustments method has been added to the SignOffProcessInstanceWorkflowService class that takes a collection of adjustment definition IDs as a parameter. This acts as a filter, and only adjustments from this collection will be executed.

Code changes in signoff-starter:

A number of code-level changes have been made to classes in the signoff-starter module to improve clarity and consistency. These are:

  • The JMXEnabler bean named JMXDatastoreEnabler, defined in PivotConfig has been renamed to jmxDatastoreEnabler.
  • The JMXEnabler bean named JMXActivePivotEnabler, defined in PivotConfig has been renamed to jmxActivePivotEnabler.
  • The JMXEnabler bean named JMXActivePivotContentServiceEnabler, defined in PivotConfig has been renamed to jmxActivePivotContentServiceEnabler.
  • The cacheService instance variable from SignOffProcessInstanceWorkflowService has been renamed to processInstanceWorkflowCacheService to avoid confusion with the cacheService method on the same class.
  • The intFormatter constant has been renamed to INT_FORMATTER to adhere to Java constant naming conventions on the following classes:
    • AdjustmentsCubeConfig
    • AdjustmentsExecutionCubeConfig
    • SignOffProcessDefinitionCubeConfig
    • SignOffProcessInstanceCubeConfig
  • The generic types on the InitialLoad methods have been renamed from DTO to D to adhere to Java generic naming conventions.
  • The constructors for the following abstract classes have been changed from public to protected: AAdjustmentsAwareAuditLogService and SecurityConfig.AWebSecurityConfigurer.
  • Nested “if” conditions have been removed from AdjustmentDiscardExecutionTask.statusConsumer.
  • In a number of places, where a local variable is created and assigned just to be returned by a method, the local variable is no longer created. This change has been made in the following classes:
    • AdjustmentWorkflowConverter
    • UserDetailsServiceConfig
    • SignOffProcessDefinitionWorkflowRestController
    • ApplicationSignOffRestClient
    • SignOffProcessInstanceWorkflowRestController
    • InstanceWorfklowConverter
  • A couple of unused private methods have been removed, including: AdjustmentExecutionDTO.getSerialVersionUID and SignOffProcessInstanceWorkflowService.getDefinitionState/.mapToString.
  • SecurityConfig.configureGlobal no longer declares an exception as part of the method signature.
  • In keeping with Spring best-practice we have removed field injection from a number of Spring Configuration classes, preferring instead to inject dependencies directly to the bean construction method. These classes are:
    • InitialLoad
    • ServletConfig
    • UserDetailsServiceConfig
  • To reduce the risk of log injection, user input is sanitized in the SignOffAdjustmentExecutionService.requestAdjustmentExecutionDeletion/.postAdjustmentRequestToServer methods before being logged.