Upgrading applications from XP7 to XP8

This section describes the steps required to upgrade an XP application from 7.x to 8.0

This section is only relevant when upgrading from XP7 to XP8.

Preparations

Before you start the upgrade procedure:

Make sure you have Enonic CLI installed
Check out the project source code to a local folder i.e. myapp/

Create a sandbox

To create the sandbox, go to your project folder and run the following command:

enonic project sandbox

When the command is completed successfully, the sandbox will be associated with your project. This enables us to build, deploy and test the application.

Using Git? Enonic CLI adds a .enonic file to your project root, consider updating your .gitignore file with the following entry:

### Enonic ###
.enonic

Build system

The standard build system used for XP projects must be updated.

Gradle Wrapper

XP 8.0 standardizes on the use of Gradle 8.14. We recommend bundling Gradle wrapper of version 8.14 or later in your project.

For simple installations, from your project root, run:

./gradle wrapper --gradle-version 8.14

This will install or update your project with a new Gradle wrapper.

Please refer to Grade documentation for more details https://docs.gradle.org/current/userguide/gradle_wrapper.html#sec:upgrading_wrapper

XP Gradle plugins

Application upgrade

If you are upgrading an application, you need to use a version greater or equal to '3.6.1' of the XP Gradle plugin (com.enonic.xp.app).

This plugin expects application properties to be defined in the app {} section of build.gradle and enables quick reference to the Enonic repo via xp.enonicRepo() shortcut

Syntax for adding plugins to Gradle may have changed for your project, we recommend the following updates to your build files:

build.gradle sample

plugins {
    id 'com.enonic.xp.app' version '3.6.1'
}

app {
    name = "${appName}"
    displayName = "${appDisplayName}"
    vendorName = "${vendorName}"
    vendorUrl = "${vendorUrl}"
    systemVersion = "${xpVersion}"
}

dependencies {
    implementation "com.enonic.xp:script-api:${xpVersion}"
    include "com.enonic.xp:lib-content:${xpVersion}"
    include "com.enonic.xp:lib-portal:${xpVersion}"
}

repositories {
    mavenCentral()
    xp.enonicRepo('dev') //TODO 'dev' is only while XP 8.0 is in development
}

Additionally, this is the recommended format for gradle.properties

gradle.properties sample

# Gradle Project settings
projectName = myproject
version = 1.0.0-SNAPSHOT

# XP App values
appDisplayName = My Cool App
appName = com.acme.something.myproject
vendorName = Acme Inc
vendorUrl = https://example.com
xpVersion = 8.0.0-SNAPSHOT #TODO 'dev' is only while XP 8.0 is in development

# Settings for publishing to a Maven repo
group = com.acme.something

appName and appDisplayName are only used for application projects, as well as app config in build.gradle

If you are upgrading a library, you don’t need to use com.enonic.xp.app plugin or have app {} section in build.gradle. Below is a sample content of build.gradle and gradle.properties files for a library:

build.gradle sample

plugins {
    id 'java'
    id 'maven-publish'
    id 'com.enonic.xp.base' version '3.6.1'
}

repositories {
    mavenCentral()
    xp.enonicRepo('dev') //TODO 'dev' is only while XP 8.0 is in development
}

You only need to use com.enonic.xp.base plugin if you are using XP dependencies and need to shortlink to Enonic repo via xp.enonicRepo() shortcut

gradle.properties sample

group=com.mycompany.lib
projectName=mylib
xpVersion=8.0.0-SNAPSHOT #TODO 'dev' is only while XP 8.0 is in development
version=1.0.0-SNAPSHOT

Verify

After completing the steps above, you should now be able to test that your build is working, using the Enonic CLI:

enonic project deploy

This command proxies the Gradle wrapper, but also connects with the project sandbox. You may also use enonic project build to build without deploying

Projects containing Java code might get build errors at this point, otherwise the build should complete successfully.

Default CMS repository

With XP 8, the default CMS repository com.enonic.cms.default is no longer created automatically. In fact, there is no default CMS repository at all. Existing com.enonic.cms.default repository is converted to a normal one without any special permissions or behavior.

Widgets

Widgets are now an API TODO

Default context

In XP 8 context repository and branch may return null if they are not set. This is a default behavior. Previously the default context was set with com.enonic.cms.default repository and draft branch.

JDK

Java 21 is required for XP 8.0.0

Testing API

If you are using Enonic testing API (com.enonic.xp:testing) You need to add Junit 5 dependency with the corresponding platform launcher.

dependencies {
testImplementation "com.enonic.xp:testing:${xpVersion}"
testImplementation(platform("org.junit:junit-bom:5.12.2"))
testImplementation 'org.junit.jupiter:junit-jupiter'
testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

test {
    useJUnitPlatform()
}

Junit 4 is not supported in XP 8.0.0

API Deprecations and Breaking Changes

HTTP Services

HTTP Services are deprecated. Universal API should be used instead.

Old services

src/
  main/
    resources/
      services/
        coolservice/
          coolservice.xml
          coolservice.js
      myservice/
        myservice.js
        myservice.xml

New APIs

src/
  main/
    resources/
      apis/
        coolservice/
          coolservice.xml
          coolservice.js
        myservice/
          myservice.js
          myservice.xml

Old service.xml

<service>
  <allow>
    <principal>role:system.admin</principal>
  </allow>
</service>

New api.xml

<api>
  <allow>
    <principal>role:system.admin</principal>
  </allow>
</api>

In order for API to work on admin tool, site or webapp, it must be mounted via the descriptor.

Example of mounting "coolservice" API in an admin tool

<tool xmlns="urn:enonic:xp:model:1.0">
  <display-name>My Admin Tool</display-name>
  <allow>
    <principal>role:system.admin</principal>
  </allow>
  <apis>
    <api>coolservice</api>
  </apis>
</tool>

Assets service

Assets service has been deprecated since XP 7.15 Use lib-asset instead.

TODO: Do we remove assets service?

lib-admin

getAssetsUri method is removed. This method was never in use since XP 7.

getBaseUri method is removed. Use getHomeToolUrl instead as a drop-in replacement.

getLocale method is removed without replacement. This method was causing issues when first user preference did not match any localization files and English was chosen as default.

getLocales method is removed. Use request.locales instead.

getPhrases method is removed. Use lib-i18n getPhrases instead.

getLauncherUrl and getLauncherPath methods are removed. Launcher is a widget now and available via widgets API.

lib-admin no longer depends on lib-portal. You need to explicitly add lib-portal dependency to your project if you are using it.

XP 7

dependencies {
    include "com.enonic.xp:lib-admin:${xpVersion}"
}

XP 8

dependencies {
    include "com.enonic.xp:lib-admin:${xpVersion}"
    include "com.enonic.xp:lib-portal:${xpVersion}"
}

lib-node

_inheritsPermissions node property is removed. It can only be used as an argument in create method - to copy permissions from the parent node.

setRootPermissions method is removed. Use applyPermissions instead.

modify method is deprecated. Use update instead.

editor of deprecated modify method can no longer edit node permissions. Use separate call to applyPermissions method instead.

lib-content

setPermissions method is removed. Use applyPermissions instead.

applyPermissions method applies permissions on published and draft content simply.

editor of deprecated modify method can no longer edit content permissions. Use separate call to applyPermissions method instead.

modify method is deprecated. Use update instead.

modifyMedia method is deprecated. Use updateMedia instead.

lib-i18n

localize method no longer accepts application parameter - because application load order is not guaranteed, trying to load foreign application localization might fail. Required localize phrases should be copied over the applications instead.

lib-repo

create method settings param is removed. This was a direct exposure of internal implementation details.

lib-task

submitNamed method is removed. Use submitTask instead.

submit method is removed. Use executeFunction instead.

Javax to Jakarta

Most of the Java EE APIs have been migrated to Jakarta EE APIs. For instance javax.servlet is replaced with jakarta.servlet.

Jetty was updated to version 12.x and now uses Jakarta EE APIs.

FasterXML Jackson JSON API

Java FasterXML Jackson JSON API is no longer a transitive dependency of XP Core API.

If you need to serialize or deserialize JSON in Java, you need to add the dependency to your project, preferably using a library different from XP internal one (FasterXML Jackson) to avoid conflicts.

We recommend using https://github.com/FasterXML/jackson-jr

FasterXML Jackson Annotations com.fasterxml.jackson.core:jackson-annotations transitive dependency is still available in JAX-RS API.

JAX-RS API

Java JAX-RS API is deprecated. It was not documented and used internally to implement legacy REST APIs.

If you have used JAX-RS API in your application, you need to migrate to the new XP 8 Universal API.

To know if you are using JAX-RS API, check for com.enonic.xp:jaxrs-api dependency in the project’s Gradle file.

Dropwizard Metrics

Java Dropwizard Metrics is no longer available in XP Core API. Migrate to com.enonic.xp.metrics Core API.

Statistics endpoint http://<host>:2609/metrics is no longer reporting Dropwizard Metrics JSON but instead reports metrics in OpenMetrics format.

Java APIs

Java Portal View Functions are no longer part of XP Core API. They were incorporated into lib-thymeleaf and lib-xslt libraries.
Java methods and classes marked as @Deprecated were removed.
Concrete collection types like LinkedList, HashMap, etc. were replaced with corresponding interfaces like List, Map, etc.
ContentService.deleteWithoutFetch was renamed to ContentService.delete for consistency with other methods.
Javax Mail is no longer a transitive dependency of XP Core API.

Others

It is no longer possible to via com.enonic.xp.server.deploy.cfg file. This method was not documented, unreliable in cluster installations and insecure.
All admin tools are now present on the launcher panel as it was stated in documentation. There is no more AdminToolDescriptor.isAppLauncherApplication API method.
Default Admin Home path is now /admin instead of /admin/home.

Upgrading applications from XP7 to XP8

Contents

Preparations

Create a sandbox

Build system

Gradle Wrapper

XP Gradle plugins

Application upgrade

Library upgrade

Verify

Default CMS repository

Widgets

Default context

JDK

Testing API

API Deprecations and Breaking Changes

HTTP Services

Assets service

lib-admin

lib-node

lib-content

lib-i18n

lib-repo

lib-task

Javax to Jakarta

FasterXML Jackson JSON API

JAX-RS API

Dropwizard Metrics

Java APIs

Others

Contents

Contents