Skip to content
Documentation

Migration

What to do when updating ProjectForge – most migrations run automatically.

Written by

1. Migration guide

Most migrations – the database schema as well as its content – run automatically when a newer version starts for the first time. Only a few changes, e.g. in configuration files or scripts, need your attention. They are listed below, newest first.

Always back up your database (and, if you still use it, the JCR repository) before an update. See Admin guide – Backup and Installation.

1.1. Version 9.0.x

  1. config.xml replaced by configuration parameters (9.0.11)

    The file config.xml in the home directory isn’t used anymore. Its settings are taken over automatically on the first start: the holidays, the JIRA servers, the contract types and the accounting settings (account number ranges and business assessment) into the configuration parameters Holidays, JIRA, Contract types and Accounting (Administration → Configuration, JSON values), each only if the parameter is still empty. Directories differing from the defaults (jcrDirectory, workingDirectory, tempDirectory, backupDirectory) are written to projectforge.properties as projectforge.dir.jcr, projectforge.dir.work, projectforge.dir.tmp and projectforge.dir.backup; databaseDirectory, loggingDirectory, storageConfig and portletMode were already without effect. Afterwards config.xml is renamed to config.xml.migrated, which may be removed. If the take-over fails (e.g. projectforge.properties not writable), the file is kept, the system dashboard reports it and the take-over is retried on the next start. The export of config.xml (Administration → System) is removed.

  2. Project contact persons (9.0.11)

    Projects now have one contact person plus any number of further contact persons, as orders do, instead of the fixed roles project manager, head of business and key account manager. The database migration (Flyway V9.0.11.1, V9.0.11.2) runs automatically: the project manager becomes the contact person (or else the head of business, or else the key account manager), the others become further contact persons; the old fields remain in the database. All contact persons have the access the three roles had. If your scripts read the old fields, switch them to the contact persons.

  3. Project numbers and number ranges (9.0.8)

    Customers and projects no longer depend on cost units: every project has a system-wide unique project number, and number ranges of customers and projects (with their mapping to Kost2) are configured in projectforge.properties (projectforge.fibu.number-ranges.*), see Admin guide – Number ranges. The database migration (Flyway V9.0.8.4) runs automatically and numbers the existing projects as their Kost2 were built: customer projects 5.<customer>.<project>, internal projects 4.<number>.<project>. An installation with Kost2 of such projects keeps the former ranges 4 and 5 without any configuration. If you configure ranges, only these apply: configure the ranges 4 and 5 as well. Projects the migration couldn’t number (customer above 999 or project number above 99) are reported by a warning on start; they get a number on their next save. Patterns of the invoicing quota apply to the Kost2 numbers as their range segments them; alternatively, projectforge.invoicing-quota.billed-by-invoiced-kost2-types=true counts the Kost2 of customer projects with an invoiced Kost2 type as billed.

  4. Log viewer and vacation settings (9.0.5)

    The admin log viewer is now a tab of the System dashboard; its own menu entry is gone, old links lead to the tab. The task and cost unit for booking vacation (projectforge.timesheet.vacation.taskId and projectforge.timesheet.vacation.kost2) are now configured on the configuration page. Values set in projectforge.properties are taken over once on the first start; afterwards they are ignored and reported as a problem on the system dashboard on every start, so please remove them from projectforge.properties. The database migrations (Flyway V9.0.5.1, V9.0.5.2) run automatically.

  5. Scripts (9.0.4)

    A stored script now always runs as stored; only the parameter values are taken from the execution form. Code executed directly (without a stored script) now runs as Kotlin instead of Groovy. Script descriptions are rich text, existing Markdown is converted on the next save.

  6. Groovy modules (9.0.4)

    Only the Groovy core and its date, JSON, XML and template modules are bundled. Groovy scripts using other modules (e.g. Ant, SQL, Swing, console) must be rewritten, e.g. as Kotlin scripts.

  7. Time sheet overlaps (9.0.4)

    Time sheets of a user on the same cost 2 may no longer overlap; saving an overlapping time sheet is rejected. Existing data is not changed. Overlap groups can be configured on the configuration page.

  8. New file store (9.0.3)

    The files (attachments, Merlin templates etc.) can now be stored in the database instead of the JCR (Apache Oak). Existing installations stay on the JCR until you switch with projectforge.files.store=db; after switching, the files are copied in the background and verified by size and checksum. Data transfer files are then kept in the file system (directory datatransfer of the ProjectForge home directory). Switching back remains possible. Please refer to Admin guide – Moving the files out of the JCR and adjust your backups: a main dump of the database plus a dump of the files.

  9. Order contact persons (9.0.2)

    Orders now have one contact person plus any number of further contact persons instead of the fixed roles project manager, head of business and key account manager. Existing entries are migrated automatically; the old fields remain in the database. If your scripts read the old fields, switch them to the contact persons.

1.2. Version 8.x → 9.0

ProjectForge 9.0 is a major update: the classic Wicket user interface was replaced by the new frontend, and all libraries were brought up to date (Spring Boot 4, Hibernate 7, Kotlin 2.3). The development builds leading up to it were published as 8.2 snapshots; the changes listed for them below are part of 9.0.

  1. Back up your database first. The schema is migrated automatically at the first start; a rollback means restoring the backup.

  2. New user interface

    All pages run in the new frontend, the only login is /next/login. Links and bookmarks of the classic pages lead to the new ones, so your users don’t need to change anything.

  3. 2FA configuration

    Expressions with /wa/…​ paths in projectforge.2fa.expiryPeriod.* don’t protect anything any more, because the Wicket pages are gone and their URLs are only redirected. Replace them by the /rs/…​ paths of the entities or by the shortcuts (e.g. ADMIN, FINANCE, HR), see Admin guide – 2FA. Check the result with Administration → System → Export 2FA configuration.

  4. Search index

    Hibernate Search was upgraded. If searching shows incomplete results after the update, rebuild the search index on the system page.

  5. User preferences

    Legacy XML user preferences are migrated to the JSON store automatically.

  6. Java

    Java 17 or newer is still required, as for 8.x (the Docker image already contains Java).

  7. Stricter validation of REST writes (8.2 snapshots)

    Saving an entity through the REST API (AbstractEntityRest.saveOrUpdate and everything built on it, i. e. the frontend as well as imports and mass updates) now validates all properties declared by @PropertyInfo / JPA @Column, and it validates the maximum length of string values too.

    + Before, two things were only checked by accident: mandatory fields were validated against a cache that was filled while a page’s layout was built, so which fields got checked depended on the pages the JVM had served since its start; and the maximum length of a string was not checked at all on this path, so an over-long value ran into the database unchecked.

    + Consequence: a write that used to be accepted silently may now be answered with HTTP 406 and a readable message naming the field. This is intended — the data was invalid before as well — but if an import or a script of yours suddenly reports a validation error, this is where it comes from. The rule itself is unchanged and lives in the entity: @PropertyInfo(required = true) and @Column(length = …, nullable = …).

1.3. Version 7.2 → 7.3

  1. MEB plugin removed

Please remove JIRA configuration (jiraConfig) in config.xml (if existing). Creation of JIRA issues through ProjectForge via incoming SMS isn’t supported anymore. You should also remove projectforge.receiveSmsKey and projectforge.cron.mebPolling from your projectforge.properties, if configured. The SMSReceiverServlet is removed as well.

  1. Scripting

    1. The scripting functionality is fully migrated to React. Multiple attachmentes are now supported. Therefore the files has to be addressed via files.file instead of file (Kotlin) or script.file (Groovy) or by files.getFile("abcdef.xlsx"). Also filenames will be accessible via files.filename instead of filename (Kotlin) or script.filename. All bindings will be done automatically for the Kotlin script (of not already there). Multiple imports will be prevented by auto-inserting of imports (and bindings).

1.4. Version 6.x to version 7

  1. Configurationparameters changed

    1. config.xml:holiday.month is now 1-based (1 - January, …​, 12 - December), was 0-based.

    2. projectforge.properties:projectforge.defaultFirstDayOfWeek=MONDAY (full name of weekday: SUNDAY, …​)

  2. Configuration parameters moved from config.xml to projectforge.properties

    1. config.xml:currencySymbol → projectforge.properties:projectforge.currencySymbol=€

    2. config.xml:defaultLocale → projectforge.properties:projectforge.defaultLocale=en

    3. config.xml:defaultTimeNotation → projectforge.properties:projectforge.defaultTimeNotation=H24

    4. config.xml:firstDayOfWeek → projectforge.properties:projectforge.defaultFirstDayOfWeek=MONDAY

    5. config.xml:excelPaperSize → projectforge.properties:projectforge.excelPaperSize=DINA4

  3. PhoneLookupServlet moved from phoneLookup to rsPublic/phoneLookup