Migration

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

• Spring boot 3 upgrade

  Scope: back-end

  Full migration instructions for this change can be found here.

• Valtimo dependencies

  Scope: back-end

  1. valtimo-dependencies and valtimo-gzac-dependencies should no longer be used for dependencyManagement or platform. This functionality has been replaced by valtimo-dependency-versions.

  2. If present, remove the dependency to org.hibernate:hibernate-envers

  3. If present, upgrade dependency org.hibernate:hibernate-core to 6.0.2.Final or higher.

• Access control files

  Scope: back-end

  1. Step 1: Find files

     Locate all files in the backend libraries matching: /resources/config/<filepath>/<filename>.permission.json

  2. Step 2: Locate permissions Locate all permissions for CamundaTask that use the assignee field. For example:

     {
         "resourceType": "com.ritense.valtimo.camunda.domain.CamundaTask",
         "action": ...,
         "conditions": [
             {
                 "type": "field",
                 "field": "assignee",
                 "operator": "==",
                 "value": "${currentUserEmail}"
             }
         ]
     }

  3. Step 3: Update permissions Change ${currentUserEmail} to ${currentUserId}.

     If the value field contains an actual email, then the email must be changed to a user ID.

• Access control database

  Scope: back-end

  1. Step 1: Find access control

     Go to the 'Admin' menu item and then to 'Access control'. Then for every role, do the steps below.

  2. Step 2: Locate permissions Locate all permissions for CamundaTask that use the assignee field. For example:

     {
         "resourceType": "com.ritense.valtimo.camunda.domain.CamundaTask",
         "action": ...,
         "conditions": [
             {
                 "type": "field",
                 "field": "assignee",
                 "operator": "==",
                 "value": "${currentUserEmail}"
             }
         ]
     }

  3. Step 3: Update permissions Change ${currentUserEmail} to ${currentUserId}

     If the value field contains an actual email, then the email must be changed to a user ID.

• Plugin action activity types

  Scope: back-end

  1. Step 1: Locate plugin actions Locate all @PluginAction annotations in the implementation code.

  2. Step 2: Update activity type Change parameter activityTypes to use the new type com.ritense.processlink.domain.ActivityTypeWithEventName. For example:

     @PluginAction(
         key = "send-email",
         title = "Send email",
         description = "Send an email with <example-product>.",
         activityTypes = [ActivityTypeWithEventName.SERVICE_TASK_START]
     )
     fun sendEmail(execution: DelegateExecution, emailProperties: EmailProperties) {
         ...

• Removed form links module

  Scope: back-end

  The form-link module was removed in favor of using the process-link module. The following changes should be made:

  1. Migrate existing form links

     Existing form link configurations should be migrated to process links. You can find a script to simplify this task here.

  2. Remove form link configuration files (optional)

     Existing form link configuration files should be removed. This is optional as the files will just get ignored.

  3. Remove existing tables (optional)

     Existing form link configurations should be removed. This is optional as the tables technically do not have to be removed. Below is a changelog that removes the tables.

     <?xml version="1.1" encoding="UTF-8" standalone="no"?>
     <databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.6.xsd">
         <changeSet author="Ritense" id="1">
             <dropAllForeignKeyConstraints baseTableName="process_form_association"/>
             <dropAllForeignKeyConstraints baseTableName="process_form_association_v2"/>
         </changeSet>
     
         <changeSet author="Ritense" id="2">
             <dropTable tableName="process_form_association"/>
             <dropTable tableName="process_form_association_v2"/>
         </changeSet>
     </databaseChangeLog>

• Removed DocumentVariableDelegate class

  Scope: back-end

  The DocumentVariableDelegate is replaced by the DocumentDelegateService class.

  1. Find all locations where DocumentVariableDelegate is used in BPMN processes and DMN decision tables.

  2. Replace DocumentVariableDelegate with the new DocumentDelegateService.

  3. Migrate all running processes to the most recent version.

• Deprecated code

  Scope: back-end

  CamundaProcessJsonSchemaDocumentService.getDocument(DelegateExecution execution) has been deprecated and removed.

  1. Find all locations where CamundaProcessJsonSchemaDocumentService is used in BPMN processes and DMN decision tables.

  2. Replace CamundaProcessJsonSchemaDocumentService with the new DocumentDelegateService.

  3. Migrate all running processes to the most recent version.

• PostgreSQL10Dialect is deprecated

  Scope: back-end

  The class org.hibernate.dialect.PostgreSQL10Dialect is deprecated, and should be replaced with org.hibernate.dialect.PostgreSQLDialect at the spring.jpa.database-platform property.

Zaaktype link moved

Scope: back-end

The Zaaktype link code has been moved from the openzaak module to the zaken-api module. This should only affect implementations that use Zaaktype links in custom code. Below is a list of the most important classes that have been moved. This list might not be exhaustive.

Old class	New class

The endpoints to manage the Zaaktype link have also been replaced:

Old endpoint	New endpoint

• Value resolvers

  Scope: back-end

  1. Step 1: Find classes Locate all Kotlin classes that extend the : ValueResolverFactory interface in the implementation code.

  2. Step 2: Locate functions In the classes found, locate all function with name handleValues(...)

  3. Step 3: Replace parameter Change the type of parameter values from: Map<String, Any> to also support null values: Map<String, Any?>.

• KvKProvider and BsnProvider

  Scope: back-end

  The new implementations of KvKProvider and BsnProvider (ZaakKvkProvider and ZaakBsnProvider) no longer depend on the openzaak module. Please make sure you have configured at least one Zaken API Plugin to make these providers work.

• Camunda webapps

  Scope: back-end

  Camunda webapps are now by default not accessible. Access can be configured with a property that allows whitelisted hosts:

valtimo:
    security:
        whitelist:
            hosts:
                - localhost
                - 0:0:0:0:0:0:0:1
                - 123.123.123.123
                - my.office.com

• Zgw case configuration

  The configuration to connect a ZGW zaak type to a case, has changed from using the connector framework to use the new plugin framework. If there was previously a zaak type connected to the case, the following steps are needed:

  1. Go to Admin > Case > Configuration

  2. Configure the 'Connected zaak type'

  The configuration to synchronize the case to an object in the Objecten API, has changed from using the connector framework to use the new plugin framework. If there was previously a case synchronisation configured, the following steps are needed:

  1. Go to Admin > Case > Configuration

  2. Configure the 'Case detail synchronisation'

• Angular and dependency upgrades

  Scope: front-end

  1. Step 1: Node and NPM upgrade Valtimo front-end libraries 12 requires Node 18. Run the following commands in your terminal (with NVM installed): nvm install 18 and nvm use 18.
  2. Step 2: Angular upgrade Valtimo front-end libraries 12 uses Angular 17. Commit all pending changes in your project and run the following command from your root directory: ng update @angular/core@17 @angular/cli@17 --force and commit all changes after the upgrade.

  3. Step 3: @valtimo/form-link to @valtimo/process-link The form-link library has been renamed to process-link.

     1. Change @valtimo/form-link to @valtimo/process-link in your package.json file.

     2. Replace all imports in your AppModule from @valtimo/form-link to @valtimo/process-link.

     3. Change the FormLinkModule to ProcessLinkModule in your AppModule.

  4. Step 4: Upgrade valtimo dependencies Change the version number of all @valtimo/** dependencies in your root package.json to the Valtimo 12 version you would like to use.

  5. Step 5: Equalize project dependencies with Valtimo dependencies In order to start your implementation, all dependency version numbers should be equal to the ones used in the

     libraries project. This can be done manually by navigating to the libraries package.json and copying over the version numbers. It can also be automatically by running the following command from the terminal when in the root of your implementation (where package.json is located). When prompted to install dependencies, answer yes.

     npx make-dir-cli tmp && npx node-wget https://raw.githubusercontent.com/valtimo-platform/valtimo-frontend-libraries/release/12.0.0/scripts/equalize-deps.cjs -d tmp/equalize-deps.cjs && node tmp/equalize-deps.cjs

  6. Step 6: Install dependencies and build project After completing the previous steps, run npm i in the root of your project to install all dependencies, and verify after that your project builds.

• Choice fields

  Scope: front-end

  1. Change the import path of ChoiceFieldService

     The ChoiceFieldsService has now been moved into the @valtimo/components library. Adjust any import paths to use this instead of @valtimo/choice-field or @valtimo/choicefield.

  2. Change import path of ChoiceField and ChoiceFieldValue

     These models can now be found in the @valtimo/components library. Adjust any import paths to use this instead of @valtimo/choice-field or @valtimo/choicefield.

  3. Adjust method names

     A few methods from the former @valtimo/choicefield library now have their names changes:

     • getChoiceFieldValuesPageByName -> queryValuesPage

     • getChoiceFieldValueById -> getValue

     • getChoiceFieldsPage -> queryPage

     • getChoiceFields -> query

  4. Remove ChoicefieldModule

     • Remove any instances of ChoicefieldModule as it no longer exists. Services and models contained in that module are now a part of @valtimo/components.

     • Do not remove the ChoiceFieldModule, with the uppercase F. This module still exists

• @valtimo/open-zaak removed

  Scope: front-end

  1. Remove dependency

  The library @valtimo/open-zaak has been removed. Remove @valtimo/open-zaak from your implementation's package.json.

  1. Remove module import

  Remove the import of OpenZaakModule from your AppModule.

  1. Remove extensions

  If used, remove emailExtensionInitializer and openZaakExtensionInitializer from initializers in your environment file. The email extension has been permanently removed. The OpenZaak extension's functionality is now included in the new library @valtimo/zgw (see below).

• Connector link extension removed

  Scope: front-end

  connectorLinkExtensionInitializer (exported from @valtimo/connector-management) has been removed and its functionality will be captured in other code. If used, remove it from initializers in your environment file.

• Extensions deprecated

  Scope: front-end

  Extensions (defined under initializers in environment files) have been deprecated. Extensions included in the libraries have been removed. If you have any custom extensions, refactor them to not use extension initializer functionality, since extensions will be removed in the next major release.

• @valtimo/contact-moment removed

  Scope: front-end

  The library @valtimo/contact-moment has been removed. Remove it from your implementation's package.json. This library included a contact moments case tab: DossierDetailTabContactMomentsComponent. This has been moved to @valtimo/zgw. The contact moments tab has been removed as a default tab in tab management. If you still want to use it, add contactmomenten: DossierDetailTabContactMomentsComponent under CASE_TAB_TOKEN in your AppModule file and configure it as a custom component tab. For more information, refer to this page. DossierDetailTabContactMomentsComponent should be imported from @valtimo/zgw.
• Zaakobjecten default tab removed

  Scope: front-end

  The zaakobjecten tab has been removed as a default tab in tab management. The zaakobjecten tab has been moved to @valtimo/zgw. If you still want to use it, add zaakobjecten: DossierDetailTabZaakobjectenComponent under CASE_TAB_TOKEN in your AppModule file and configure it as a custom component tab. For more information, refer to this page. DossierDetailTabZaakobjectenComponent should be imported from @valtimo/zgw.
• @valtimo/customer removed

  Scope: front-end

  The library @valtimo/customer has been removed, and its functionality has been moved to @valtimo/zgw. Remove it from your implementation's package.json, and change the import of CustomerModule from @valtimo/customer to @valtimo/zgw in app.module.ts if you use this functionality.

• OpenZaak uploader provider deprecated

  Scope: front-end

  The OpenZaak upload provider has been deprecated and will be removed in the next major release. This provider is active if uploadProvider in your environment file is set to UploadProvider.OPEN_ZAAK.

• Form.io Documenten API uploader component moved

  Scope: front-end

  The Documenten API form.io upload component has been moved from @valtimo/dossier to @valtimo/zgw. If this upload component is included in your project, import ZgwModule into your AppModule in app.module.ts and change the import of registerDocumentenApiFormioUploadComponent from @valtimo/dossier to @valtimo/zgw.

• New library: @valtimo/zgw

  A refactor has been made to move all ZGW functionality previously included in default Valtimo libraries to its own, optional dependency: @valtimo/zgw. Please install this dependency into your implementation and import ZgwModule (which it exports) into your AppModule if you use ZGW functionality. If ZgwModule is imported, the following functionality is included:

  • Documenten API documents tab. If uploadProvider is set to UploadProvider.DOCUMENTEN_API in your environment file, and ZgwModule is not imported, a not found message will be displayed on the case documents tab.

  • A new ZGW tab on the case management admin page.

  • The component to display object tabs based on the caseObjectTypes configuration in your environment file. If ZgwModule is not imported, and this configuration is present, a not found message will be displayed on the tabs.

  • Functionality on the case admin configuration tab to:

    • Link an upload process to a case definition

    • Configuration for case detail synchronisation

    • Configuration for connection a zaak type to a case definition

• Removed: @valtimo/exact-plugin

  The library @valtimo/exact-plugin has been removed. All of its code is now exported from @valtimo/plugin. Remove @valtimo/exact-plugin from your implementation's package.json if it's included, and change imports throughout your implementation from @valtimo/exact-plugin to @valtimo/plugin.

• Removed: @valtimo/view-configurator

  1. If present, remove library @valtimo/view-configurator from the package.json.

  2. If present, remove the module ViewConfiguratorModule from your AppModule.

• Task management

  Scope: front-end

  1. Add dependency

  Add the dependency @valtimo/task-management to your implementation. Make sure to run a fresh npm install after.

  1. Import library

  In app.module.ts, add the following line to the top of the file with the imports: import {TaskManagementModule} from '@valtimo/task-management';

  1. Add task management module to imports

  Add the previously imported TaskManagementModule to the imports array of your AppModule.

  1. Add menu entry

  Add the following line under the admin section in the menu configuration in the environment file of your implementation: {link: ['/task-management'], title: 'Tasks', sequence: {UNIQUE_SEQUENCE_NUMBER}}, Replace UNIQUE_SEQUENCE_NUMBER with a unique sequence number, and make sure the sequence numbers of other menu items on the admin layer remain unique.

• Feature toggles

  Scope: front-end

  1. If present, remove the feature toggle caseSearchFields from all your environment.*.ts

  2. If not present, set the feature toggle enableObjectManagement to false in all your environment.*.ts

• Dark-mode and theme-switching

  Scope: front-end

  1. Change stylesheets

     In order for the themes to be displayed properly, the following change has to be made in the styles array in angular.json in the root of your implementation:

     1. If present, change "dist/valtimo/components/assets/css/carbon-beagle-compatibility.scss" to "dist/valtimo/components/assets/css/compatibility.scss".

     2. If present, change "node_modules/@valtimo/components/assets/css/carbon-beagle-compatibility.scss" to "node_modules/@valtimo/components/assets/css/compatibility.scss".

     3. Make sure they both are initiated after ".../valtimo/components/assets/css/carbon.scss"

  2. Add logo variants

     Next to logoSvgBase64 and logoPngBase64, there is now also support for dark-mode variants called darkModeLogoSvgBase64 and darkModeLogoPngBase64. In order for the logo's to be displayed properly in both light- and dark-mode, the following changes have to be made:

     • Add the desired logos in logo.ts

       const LOGO_BASE_64 = 'Base 64 string for the light-mode (default) SVG logo goes here';
       
       const DARK_MODE_LOGO_BASE_64 = 'Base 64 string for the dark-mode SVG logo goes here';
       
       const LOGO_BASE_64_PNG = 'Base 64 string for the light-mode (default) PNG logo goes here';
       
       const DARK_MODE_LOGO_BASE_64_PNG = 'Base 64 string for the dark-mode PNG logo goes here';
       
       export {LOGO_BASE_64, DARK_MODE_LOGO_BASE_64, LOGO_BASE_64_PNG, DARK_MODE_LOGO_BASE_64_PNG};
     • Import the logos and assign them in environment.ts

       /* Import the logo's from the logo.ts file */
       import {
         DARK_MODE_LOGO_BASE_64,
         DARK_MODE_LOGO_BASE_64_PNG,
         LOGO_BASE_64,
         LOGO_BASE_64_PNG,
       } from './logo';
       
       export const environment: ValtimoConfig = {
         logoSvgBase64: LOGO_BASE_64,
         darkModeLogoSvgBase64: DARK_MODE_LOGO_BASE_64,
         logoPngBase64: LOGO_BASE_64_PNG,
         darkModeLogoPngBase64: DARK_MODE_LOGO_BASE_64_PNG
       }

  The logo's should now automatically update when themes are switched.