Migration

This page describes how to update Valtimo from the previous version to the current.

  • Change in Recipient.Type values

    Scope: back-end

    To meet coding standards, the Enum values of com.ritense.valtimo.contract.mail.model.value.Recipient.Type have been changed to all uppercase. References to these Enum values should be changed in implementations:

    • Change uses of Type.To to Type.TO

    • Change uses of Type.Cc to Type.CC

    • Change uses of Type.Bcc to Type.BCC

  • Rename application property valtimo.jwt.secret

    Scope: back-end

    1. Find valtimo.jwt.secret

      Find all occurrences of valtimo.jwt.secret and rename them all to valtimo.oauth.public-key. This property is usually found in the application.yml.

    2. Find VALTIMO_JWT_SECRET

      Find all occurrences of VALTIMO_JWT_SECRET and rename them to VALTIMO_OAUTH_PUBLIC_KEY. This environment variable can potentially be found in many different places such as:

      • .env.properties file inside the repository

      • AWS Parameter store

      • Kubernetes .yaml file

  • Rename application property valtimo.jwt.tokenValidityInSeconds

    Scope: back-end

    1. Find valtimo.jwt.tokenValidityInSeconds

      Find all occurrences of valtimo.jwt.tokenValidityInSeconds and rename them all to valtimo.oauth.tokenValidityInSeconds. This property is usually found in the application.yml.

    2. Find VALTIMO_JWT_TOKEN_VALIDITY_IN_SECONDS

      Find all occurrences of VALTIMO_JWT_TOKEN_VALIDITY_IN_SECONDS and rename them to VALTIMO_OAUTH_TOKEN_VALIDITY_IN_SECONDS. This environment variable can potentially be found in many different places such as:

      • .env.properties file inside the repository

      • AWS Parameter store

      • Kubernetes .yaml file

  • Whitelist all services used in Camunda processes

    Scope: back-end

    1. Find all services used in processes and decision tables

      Open all BPMN and DMN files and list all the services and other java/kotlin classes that are used.

    2. Find all services in code

      All the listed services must then be found inside the java/kotlin code.

    3. Whitelist the service

      Whitelisting a service should be done in one of two different ways:

      1. Either, add @ProcessBean above the class. For example:

        @ProcessBean
@Service
class MyCustomClass {
    ...

      2. Or add @ProcessBean above the bean definition. For example:

        @ProcessBean
@Bean
@ConditionalOnMissingBean(MyCustomService::class)
fun myCustomService(...): MyCustomService {
    return MyCustomService(...)
}

  • Remove the use of authority and contexts entities

    Scope: back-end

    1. Find and delete the use of authority classes as they are no longer supported

      • AuthorityResource.java

      • AuthorityService.java

      • AuthorityRepository.java

      • AuthorityCreatedEvent.java

      • AuthorityDeletedEvent.java

      • AuthorityEvent.java

      • AuthorityNameChangedEvent.java

      • Authority.java

      • AuthorityRequest.java

      • Money.java

    2. Find and delete the use of context classes as they are no longer supported

      • ContextResource.java

      • ContextService.java

      • ContextRepository.java

      • UserContextRepository.java

      • UserContextDTO.java

      • Context.java

      • ContextProcess.java

      • MenuItem.java

      • UserContext.java

  • Angular and dependency upgrades

    Scope: front-end

    1. Upgrading Angular

      • The Valtimo front-end libraries have been upgraded from Angular 14 to Angular 16 in major 11. In order to use them, your implementation also needs to upgrade to Angular 16.

      • Follow this guide to upgrade from Angular 14 to Angular 15. You will probably need to use ng update commands with the --force option at the end.

      • After the migration is complete, commit your changes.

      • Follow this guide to upgrade from Angular 15 to Angular 16. You will probably need to use ng update commands with the --force option at the end.

      • After the migration is complete, commit your changes.

      • Verify whether all Angular related dependencies in the package.json in the root of your project are at version 16. If some have been skipped, check https://www.npmjs.com/ for their latest version and upgrade them manually.

    2. Removing dependencies

      • Some dependencies have been removed from the Valtimo front-end libraries. It is advised to remove them from your implementation as well.

      • @angular/flex-layout has been deprecated. Remove it from your implementation. To replace its directives, we advise to write regular CSS classes with flexbox styling.

      • If your implementation does not use any @angular/material related dependencies, and they are included in your package.json dependencies, we advise to remove them.

    3. Locking dependencies

      • In Valtimo front-end libraries, all dependencies not related to Angular have been locked to specific versions, in order to avoid issues which are frequently encountered with automatic minor or patch dependency upgrades.

      • We advise you to do the same; lock all dependencies except for the ones related to Angular. You can achieve this by removing tilde ~ and caret ^ symbols from your implementation's package.json.

      • Next, we advise you to lock your dependencies to the same versions used in the Valtimo front-end libraries. A non-exhaustive list of dependencies and their versions is included below. If you cannot find your dependency in the list below, refer to the major 11 front-end libraries package.json here.

      package.json

      {
  ...
  "dependencies": {
    ...
    "@mdi/font": "7.2.96",
    "@bpmn-io/dmn-migrate": "0.4.3",
    "@webcomponents/custom-elements": "1.6.0",
    "bpmn-js-properties-panel": "0.46.0",
    "core-js": "3.32.0",
    "dmn-js": "12.3.0",
    "dropzone": "6.0.0-beta.2",
    "flatpickr": "4.6.13",
    "json-server": "0.17.3",
    "ngx-color-picker": "14.0.0",
    "ngx-logger": "5.0.12",
    "ngx-translate-multi-http-loader": "16.0.1",
    "popper.js": "1.16.1",
    "rxjs": "7.8.1",
    "swagger-ui": "5.4.2",
    "tslib": "2.6.2",
    "zone.js": "0.13.1"
  },
  "devDependencies": {
    ...
    "@types/jasmine": "4.3.5",
    "@types/jasminewd2": "2.0.10",
    "@types/node": "20.5.0",
    "codelyzer": "6.0.2",
    "deepmerge-ts": "5.1.0",
    "jasmine-core": "5.1.0",
    "jasmine-spec-reporter": "7.0.0",
    "karma": "6.4.2",
    "karma-chrome-launcher": "3.2.0",
    "karma-coverage-istanbul-reporter": "3.0.3",
    "karma-jasmine":"5.1.0",
    "karma-jasmine-html-reporter":  "2.1.0",
    "ts-node": "10.9.1",
    "typescript": "5.1.6"
  }
}

    4. Adding dependencies

      • @valtimo/access-control, should be added to your implementation as it is a required dependency.

    5. Changing typescript config

      • In tsconfig.json in the root of your implementation, change module to es2020 and also change es**** in the lib array to es2020.

  • Change in Carbon Design System version

    Scope: front-end

    1. Install new Carbon Dependencies

      • Delete node_modules.

      • Run 'npm install --legacy-peer-deps'.

    2. Update all carbon selectors from 'ibm' to 'cds'

      Tags:

      Deprecated:
<ibm-placeholder></ibm-placeholder>

Active:
<cds-placeholder></cds-placeholder>

      Directives:

      Deprecated:
<button ibmButton="primary"></button>

Active:
<button cdsButton="primary"></button>

      Classes:

      Deprecated:
<svg class="ibm--btn__icon"></svg>

Active:
<svg class="cds--btn__icon"></svg>

    3. Remove all usages of @carbon/icons-angular

      Icon:

      Deprecated:
<svg class="ibm--btn__icon" ibmIconArrowDown size="16"></svg>

Active:
<svg class="cds--btn__icon" cdsIcon="arrow--down" size="16"></svg>

    4. Registering @carbon/icons

    5. In order to use @carbon/icons, the IconModule needs to be imported.

      sample.module.ts

      ...
// import IconModule
import {IconModule} from 'carbon-components-angular';
...

@NgModule({
    ...
    imports: [
      ...
      IconModule
      ...
    ]
    ...
})
export class SampleModule {
 ...
}

    6. Some icons may not be available by default, so they need to be registered in the component where they are needed. This is accomplished via the Carbon IconService

      sample.component.ts

      ...
// import IconService
import {IconService} from 'carbon-components-angular';
...
// import Icons
import {ArrowDown16, ArrowUp16} from '@carbon/icons';
...

@Component({
    ...
})
export class SampleComponent implements OnInit{
 ...
 constructor(private readonly iconService: IconService) {}
 ...
 public ngOnInit(): void {
  this.iconService.registerAll([ArrowDown16, ArrowUp16]);
 }
 ...
}

    7. All icons available through the Carbon library can be found here

  • Remove deleted admin menu items

    Scope: front-end

    1. Remove @valtimo/context

      • Remove @valtimo/context library from the package.json.

      • Remove ContextModule module from the app.module.ts.

    2. Remove @valtimo/management

      • Remove @valtimo/management library from the package.json.

      • Remove ManagementContextModule module from the app.module.ts.

      • Remove the Contexts link from the environment.ts

    3. Remove @valtimo/user-management

      • Remove @valtimo/user-management library from the package.json.

      • Remove UserManagementModule module from the app.module.ts.

      • Remove the Users link from the environment.ts

    4. Remove @valtimo/authority

      • Remove @valtimo/authority library from the package.json.

      • Remove AuthorityModule module from the app.module.ts.

      • Remove the Entitlements link from the environment.ts

  • Form-links page

    Scope: front-end

    1. environment.ts

      Go to the environment.ts file and change this line:

      {link: ['/form-links'], title: 'Form links'...

      To this line:

      {link: ['/process-links'], title: 'Process links'...

  • Update connector and plugin keys

    Scope: back-end/front-end

    In order for keys to be encrypted with GCM (as apposed to ECB, see here for more information), all existing plugin configurations need to be updated.

    1. Save existing connector configurations with their keys

    2. Save plugin configurations with their keys

    3. See if encryption is used anywhere else in the application

  • Removal of @valtimo/user-interface library

    Scope: front-end

    1. Remove @valtimo/user-interface as a dependency

      The library @valtimo/user-interface has been removed. All of its components, directives and services have been been moved to @valtimo/components. In order to migrate, remove @valtimo/user-interface as a dependency in your implementation.

    2. Change stylesheet in angular.json

      The angular.json file in the root of your implementation includes the following value:

      "node_modules/@valtimo/user-interface/assets/design-tokens.css"

      This should be changed to:

      "node_modules/@valtimo/components/assets/css/design-tokens.css"

    3. Change imports

      Most components, services and directives from @valtimo/user-interface are now exported from @valtimo/components. Search your implementations for any imports and change them accordingly.

    4. Renamed components

    The component v-multi-input has been renamed to valtimo-carbon-multi-input. If it is used anywhere in your implementation, change the selector.

    ModaleModule exported from @valtimo/user-interface is renamed to VModalModule.

    CardModule exported from @valtimo/user-interface is renamed to VCardModule.

  • Update of CarbonTable for backwards compatibility

    Scope: front-end

    Updates in the @Input fields:

    • @Input paginationConfig -> @Input paginatorConfig

    • @Input fields has been added instead of having the columnConfigs in the tableConfig. ColumnConfig now extends the ListField for backwards compatibility.

    • Remove fields property from any instances of CarbonTableConfig as it is no longer a part of the interface

  • Enable the JSON PBAC editor

    Scope: front-end

    Change in angular.json

    1. Go to the file angular.json.

    2. Locate the array with assets: projects.architect.build.options.assets.

    3. Add the monaco-editor:

    {
    "glob": "**/*",
    "input": "node_modules/monaco-editor",
    "output": "assets/monaco-editor"
}

  • Add PBAC dependencies and menu items

    Scope: front-end

    1. Add PBAC dependencies

    Run npm i @valtimo/[email protected] @valtimo/[email protected] in the root of your implementation.

    1. AppModule

    Add the following line to the top of app.module.ts:

    import {AccessControlManagementModule} from '@valtimo/access-control-management';

    Next, add AccessControlManagementModule to the imports array of AppModule.

    1. Access control management menu item

    Add the following to the admin menu items in your environment config:

    {link: ['/access-control'], title: 'Access Control', sequence: UNIQUE_SEQUENCE_NUMBER}

    Make sure to update UNIQUE_SEQUENCE_NUMBER with a unique sequence number.

  • Moved Verzoek plugin property objectManagementId

    Scope: back-end

    1. Locate any .pluginconfig.json file

      Go to the /resource folder of you project and locate any file ending with .pluginconfig.json.

    2. Find the verzoek plugin configurations

      Every .pluginconfig.json can contain Verzoek plugin configuration. This plugin can be recognized where the property pluginDefinitionKey is verzoek.

    3. Move the objectManagementId

      Every Verzoek plugin configuration has a field called objectManagementId. This field should be moved out of the properties field and into every verzoekProperties field.

  • Configure access control roles and permissions

    Scope: back-end

    Roles and permissions need to be configured as described here.

PreviousValtimo frontend librariesNext10.x.x