ScipioERP

Upgrading from Scipio ERP 3.x to 4.0: a checklist

What to check before you move a Scipio ERP 3.x project to 4.0: the JDK and the build, the libraries that were replaced and what your own code must change, the XML that still loads, the new backend theme and URLs, and the new license.

AI-generated illustration: a navy staircase rising to the right, its steps edged in crimson, a small arrow climbing it
Image generated by AI

Scipio ERP 4.0 changes more under the surface than any release before it. Most of it does not touch a project that runs on 3.x, but some of it does. This list comes from the changes in the 4.0 code. Work through it on a copy of your installation, not on production.

1. The JDK and the build#

  • 4.0 builds and runs on a Java 11, 17 or 21 JDK. The source level is Java 11; with a JDK 17 or newer the build uses a Java 17 toolchain.
  • The build is Gradle (wrapper 8.5). The Ant build is gone.
  • Components in hot-deploy/ and addons/ are found automatically.

A fresh start is two commands:

bash
./gradlew build loadDemo
./gradlew start

2. Sync the libraries once#

After you merge 4.0 into your project, run this once:

bash
./gradlew syncLibs

It mirrors the library folder, so the jars that 4.0 no longer uses leave framework/base/lib/gradle. Skip it, and an old jar stays on the classpath beside its replacement.

3. The libraries that changed#

For 4.0 we replaced or removed a set of libraries: some were outdated, some were unused, and some did not fit the license policy of the release. If your own components use one of them, this is what changes:

BeforeIn 4.0What your code must do
Apache Tika 1.28.5 (tika-parsers)Tika 3.3.2: tika-core, the text module and the PDF moduleUse TikaCoreProperties.RESOURCE_NAME_KEY instead of Metadata.RESOURCE_NAME_KEY. Add a parser module you need yourself, for example tika-parser-microsoft-module for Office files.
Apache PDFBox 2.0.30PDFBox 3.0.8PDFBox 3 loads a document with Loader.loadPDF(...) instead of PDDocument.load(...).
iText 2.1.7OpenPDF 1.3.43Nothing. OpenPDF keeps the com.lowagie packages.
groovy-all 3.0.19groovy, groovy-jsr223, groovy-dateutil 3.0.19If your tests use JUnit, declare it in your component. It no longer comes in through groovy-all.
Jakarta ORO 2.0.8java.util.regexReplace imports of org.apache.oro. PatternFactory.createOrGetPerl5CompiledPattern now returns a java.util.regex.Pattern.
javax.servlet-api, javax.servlet.jsp-api jarsThe API that Tomcat providesNothing, unless your component ships its own servlet API jar: remove it.
commons-el, gmetric4j, metrics-ganglia, axis2-codegen at runtimeRemovedAdd them to your own component if you really use them.

Then test the places where a replacement can behave differently:

  • Regular expressions: ORO and java.util.regex differ in rare cases.
  • MIME type detection of .docx and .xlsx files read from a stream.
  • PDF import, if you use content documents or surveys built from PDFs.
  • JSP pages, and SOAP clients that use Axis2.

4. Your XML still loads#

In 4.0 every definition can be a Java annotation: services, entities, controllers and the screen, form and menu widgets. Every application we ship has been converted. Your own XML definitions still load next to them, and ofbiz-component.xml is still read beside scipio-component.xml, so nothing forces you to convert on the day you upgrade.

When you want to, one Gradle task converts a component, and a second one removes the XML it replaced:

bash
./gradlew convertXmlToAnnotation -Pcomponent=mycomponent
./gradlew removeMigratedXml -Pcomponent=mycomponent -PdryRun=true

We walk through a conversion in a separate post. The reference is in the documentation: Annotations .

5. The backend looks different#

  • The default backend theme is Aurora, set with VISUAL_THEME=AURORA in framework/common/config/general.properties. The older themes still ship in themes/, so a project that depends on one can set it back. See Aurora .
  • Backend addresses leave out /control/, for example /cms/pages. Old links with /control/ keep working, so bookmarks and your own links do not break.

6. The license#

Scipio ERP 4.0 is licensed under the AGPL-3.0, with a commercial license beside it. Scipio ERP 3.x stays under the Apache License 2.0. Before you upgrade a project that you changed or that you sell, read what the AGPL-3.0 means for your shop , and decide which of the two licenses fits.

7. What you get#

The reason to do all of this: the annotations and the converter, an MCP server in every application so that the agent you already use can operate the system, a rebuilt manufacturing application, e-invoicing to the European standard, and the Aurora backend. The full list is in the release notes .

If your project is large, or you would rather not do the upgrade alone, talk to us .

More news