Migration notes 6.0

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

Migrate to 6.0.1

Upgrading from version 6.0.0 See Atoti Sign-Off 6.0.1 Release Notes.

Headline announcement

• Persisting full scope paths: Full scope paths are persisted to the JPA layer to allow handling of scopes with slicing and non-slicing hierarchies.
• Customized sign-off status feed: The sign-off status feed member for “in review” representation can be customized on the application server.

Using full scope paths in persisted data

Older versions of Atoti Sign-Off did not include the full scope path for definitions that were saved to the JPA layer. As of this version, full scope paths will be used. For example, if you have a definition on the slicing Book level, the old path would look like:

[Booking].[Books].[Book]=[BS_MGT_FX]

The new path will look like:

[Booking].[Books].[Book]=[AllMember].[BS_MGT_FX]

To migrate scope paths created before Atoti Sign-Off 6.1.0, we have added a migration endpoint. The reason for adding an endpoint rather than a script is that we need to connect with the application server to get the full scope path.

To run the migration, do the following:

1. Start your application server.
2. Start Atoti Sign-Off with the 6.0.1-migration Spring profile to include the endpoint and override default validation.
3. Run the migration endpoint. You can do this via Swagger by executing the POST request at <base URL>/sign-off/rest/v2/migrate/sign-off-definition-scopes.
   The migration endpoint retrieves the full scope paths from the application server and updates the definitions if necessary.
4. Restart the application server and Atoti Sign-Off as normal (without the 6.0.1-migration profile) to view your updated definitions and proceed as normal.

Configuration properties

Properties added

signoff-activeviam

Properties modified

signoff-activeviam

Migrate to 6.0.0

Upgrading from version 5.3.0 See Atoti Sign-Off 6.0.0 Release Notes.

Atoti Sign-Off is using Atoti Server 6.1.4, Atoti UI ~5.2.6, and Sign-Off API 4.2.0 .

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

• Atoti UI documentation and Atoti UI Migration Notes
• Release notes for Atoti Server
• Release notes for Signoff API

Headline announcement

• Interactions with Sign-Off workflows: The way workflows change state (APPROVED, PENDING, and so on) has been updated to make customization easier. For more details, see Workflow task actions.
• Workflow services moved: Both SignOffProcessInstanceWorkflowService.java and SignOffProcessDefinitionWorkflowService.java have been migrated from signoff-starter to signoff-activeviam module along with their dependency classes.
• Additional field for Definitions: A linkedDashboardId field has been added to the SignOffProcessDefinitionEntity. This field lets you link a dashboard to the definition in the UI.
• Artifact relocation: The released artifacts are now released under the group id com.activeviam.solutions.signoff. See updated locations.
• Adjustment upload/download: Adjustments can now be created by uploading CSV files. Please see the Upload Adjustments section. In addition, you can export adjustments into a CSV file.
• Definition upload/download: Definitions can now be created by uploading CSV files. In addition, you can export definitions into a CSV file. See Upload tasks.
• Restart tasks with adjustments: Tasks can now be restarted while maintaining adjustments that were previously executed.
• Simplified UI settings: The UI settings have been simplified. Settings that were previously duplicated in both the UI and server can now be set only on the server.
• Removal of dashboard widgets: The Atoti Sign-Off dashboard widgets have been replaced with dedicated screens.

Breaking changes

Database changes

The following changes have been made to the database schema and require manual migrations:

Default schema change

The default schema for all tables has been changed to sign-off. This is to facilitate using the same database for multiple ActiveViam products. For example, if you use Atoti FRTB, Atoti Sign-Off, and Atoti Limits, you can use the same database for all three products, and specify a different schema for each.This will result in a database structure as follows:

- Database
      - frtb 
         - frtb-datasource-1
         - frtb-datasource-2
      - sign-off
         - signoff-datasource-1
         - signoff-datasource-2
      - limits
         - limits-datasource-1
         - limits-datasource-2

This helps manage the database structure and allows for easier maintenance.

Our reference implementation uses a H2 database as a sample, but in production we recommend using a production-grade database. If you don’t already, you should migrate your data away from H2 towards a production-grade database.

If you use a production-grade database and have already defined a schema for your database, you only need to migrate the following properties to your schema:

spring.activiti.database-schema=your_schema
activiti.datasource.properties.hibernate.default_schema=your_schema
application.datasource.properties.hibernate.default_schema=your_schema
audit-log.datasource.properties.hibernate.default_schema=your_schema

If you use a production-grade database, have not yet defined a schema and you don’t want to use the product-default schema, you can remove these properties from your application.yml. This will result in the database using the default schema of the database provider.

If you use a production-grade database, have not yet defined a schema and you want to use the default schema sign-off, create the schema in your database. How this is done depends on the database. See the following links for popular implementations:

• Postgresql
• MySQL
• MSSQL

linkedDashboardId field

A linkedDashboardId field has been added to the SignOffProcessDefinitionEntity. This field is used to link a dashboard to the definition in the UI. You will need to add this column to the processDefinition table in your database. This can be done by executing the following SQL statement:

ALTER TABLE "sign-off"."processDefinition" ADD COLUMN "linkedDashboardId" VARCHAR(255);

Removal of measures field

The measures field has been removed from the AWorkflowProcessDefinitionEntity class as it is not used. You should remove this column from the processDefinition table in your database. This can be done by executing the following SQL statement:

ALTER TABLE "sign-off"."processDefinition" DROP COLUMN "measures";

This is not required to start Atoti Sign-Off but is recommended to keep your database schema clean.

Restarting tasks with adjustments

The UI will now prompt users if they want “Retain existing adjustments” when restarting a task. The default behavior is to retain adjustments, but this can be changed by setting the sign-off.workflow.keep-adjustments-when-restarting-task property to false. If users elect not to retain adjustments, the task will be restarted and the adjustments will be deleted. This is the same as the previous behavior.

Artifact changes

The signoff-activeviam and signoff-starter artifacts are now released under a new group ID:

<dependency>
    <groupId>com.activeviam.solutions.signoff</groupId>
    <artifactId>signoff-activeviam</artifactId>
</dependency>

<dependency>
    <groupId>com.activeviam.solutions.signoff</groupId>
    <artifactId>signoff-starter</artifactId>
</dependency>

JPA entity changes

The SignOffProcessInstanceEntity and SignOffProcessDefinitionEntity classes are now updated to their current version in their respective JPA repositories. This differs from the previous behavior where the repositories were append-only.

Default workflow changes

The following changes have been made to the default workflows:

1. In order for a user to view tasks in the new Atoti Sign-Off screens, the task workflows must have the same user access as their parent definition. We have updated our default workflows to reflect this requirement.
2. If you have custom workflows with statuses and actions different to the defaults, then you must expose an implementation of ISignOffWorkflowStatusActionManager. This allows Atoti Sign-Off to understand the statuses and actions of your custom workflows and thus apply application logic.
3. Task approvals for the default workflows cannot be approved by the previous user in the workflow. This can be changed by setting sign-off.workflow.approver-can-be-same-as-previous-user=true.

Sign Off Process Definition

The following changes have been made in the sign-off-process-definition workflow:

• A new service task CREATING has been added at the start of the workflow. This task persists JPA entities on creation of the workflow. Previously, the entities were persisted during the PUBLISHING task.
• This workflow is visible to users with the ROLE_USERS once created. Previously, SAVED or PUBLISHED definitions were only visible to users with the ROLE_MANAGERS.

Workflow Service changes

The following changes have been made to the workflow services:

• The signature of the ISignOffProcessInstanceWorkflowService:initiate method has been updated from AHistoryRecordDTO initiate(SignOffProcessInstanceDTO object, String comment) to AHistoryRecordDTO initiate(SignOffProcessInstanceDTO object, Map<String, Object> variables) to pass optional variables to the worklfow. If you have a custom implementation of this workflow you will need to update the method signature.

REST method changes

• The endpoint POST /sign-off-process-instance which initiates a task now accepts an optional boolean keepAdjustments query parameter. If not provided, this value defaults to the value of the sign-off.workflow.keep-adjustments-when-restarting-task property, which out of the box defaults to true;

JPA changes

Atoti Sign-Off now relies on the JPA layer as the true source of data, rather than the workflow. As such, the JPA entities are now updated to their current version in their respective JPA repositories. This differs from the previous behavior where the repositories were append-only. To do this, the updatable = false annotation value that was previously present has been removed from the following entities:

• SignOffProcessInstanceEntity
• SignOffProcessDefinitionEntity
• AWorkflowProcessDefinitionEntity
• ABitemporalObjectEntity

Workflow object changes

The SignOffProcessDefinitionDTO::measures field has been removed as it is not used.

Definitions on overlapping scopes

Users are now prevented by default from creating Atoti Sign-Off definitions on overlapping scopes. For more information please see the section on Overlapping Scopes.

Dashboard widgets

Dashboard widgets have been replaced with dedicated screens for the task and definition management. Dashboards can be migrated using the migration script provided here.

UI settings

Settings that were previously hardcoded in the UI are now fetched from the server. These properties are configurable. For example, if you are connecting with Atoti Market Risk we recommend you use a profile like the MR profile to set the required properties. That could look as follows:

sign-off:
  application:
    settings:
      adjustment-reasons:
        - Wrong Market Data
        - Missing Trade
        - Wrong Input Data
        - Unknown
      as-of-date-dimensions:
        MR:
          cube-dimension:
            "[*]":
              as-of-date:
                dimension-name: Dates
                hierarchy-name: Date
                level-name: AsOfDate
      restricted-cubes:
        MR:
          - VaR-ES Summary Cube
          - Sensitivity Summary Cube
          - PL Summary Cube
          - Market Data Cube
          - MRCombinedCube
      available-scope-levels:
        MR:
          available-levels-by-cube:
            "[*]":
              - dimension-name: Organization
                hierarchy-name: BookHierarchy
                level-name: Level 5
              - dimension-name: Booking
                hierarchy-name: Books
                level-name: Book
              - dimension-name: Booking
                hierarchy-name: Desks
                level-name: Desk
      adjustment-level-coordinate:
        dimension-name: Sign-Off
        hierarchy-name: Adjustment
        level-name: Source
      feed-level-coordinate:
        dimension-name: Sign-off
        hierarchy-name: Sign-off Status
        level-name: Feed

Note that it is your responsibility to configure the required fields. The class SignOffApplicationUISettings provides more details on the properties that can be set.

Input files

Added

Modified

Configuration

Configuration properties

Properties added

signoff-activeviam module

Configuration files

Files Modified

RestApiProperties.java

Updated properties:

UI settings

Updated properties:

Deleted properties:

application.yml

New properties:

Updated properties:

Datastores

Modified stores

Other changes

Spring Boot compliance

Atoti Sign-Off now aligns more closely with Spring Boot best practices in our aim to move towards using Spring Boot Starters to ease migrations.

Configuration Properties

Atoti Sign-Off now uses Spring Configuration Properties to help externalize configurations for users. You can see a full list of the provided properties in the Configuration Properties section.

Adjustments locations and input fields

These two adjustment fields are now Lists instead of Sets. This impacts the following classes and services that may affect your implementation:

Workflow-related:

• SignOffProcessInstanceWorkflowService.java
• AuditableAdjustmentDefinitionDTO.java
• AdjustmentExecutionDTO.java

JPA-related:

• AdjustmentsDefinitionEntity.java
• AdjustmentsFiltersConverter.java
• AdjustmentsInputConverter.java
• IAdjustmentDefinition.java
• AdjustmentExecutionEntity.java
• IAdjustmentExecution.java

Status manager service

The ISignOffWorkflowStatusManager lets you implement a service to define the statuses that relate to specific categories. Current methods with a default implementation in DefaultSignOffWorkflowStatusManager are:

• getLiveDefinitionStatuses(): returns a list of definition status considered live.
• getPendingApprovalTaskStatuses(): returns a list of task status considered pending.

Workflow task actions

A unique way is now used to execute common workflow task actions (e.g. approve, reject, request approval …) and custom actions. It allows greater flexibility and easier extension of current set of actions. To extend the task actions, see Adding Custom Workflow Tasks.