Upgrading applications from XP7 to XP8
Contents
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 has 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 ### .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 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: |
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 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 |
Library upgrade
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:
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 |
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. APIs should be used instead.
src/
main/
resources/
services/
coolservice/
coolservice.xml
coolservice.js
myservice/
myservice.js
myservice.xml
src/
main/
resources/
apis/
coolservice/
coolservice.xml
coolservice.js
myservice/
myservice.js
myservice.xml
<service>
<allow>
<principal>role:system.admin</principal>
</allow>
</service>
<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.
<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.
node-lib
_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.
content-lib
setPermissions
method is removed. Use applyPermissions
instead.
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-io
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.
Javax to Jakarta
Most of the Java EE APIs have been migrated to Jakarta EE APIs. Most noticeable ones are:
-
javax.servlet
tojakarta.servlet
-
javax.mail
tojakarta.mail
FasterXML Jackson JSON API
Java FasterXML Jackson JSON API is no longer 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 REST APIs.
If you have used JAX-RS API in your application, you need to migrate to the new XP8 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.
Others
-
it is no longer possible to install applications by specifying a url in
-
All admin tools are now present on the launcher panel - as it was stated in documentation. There is no more
AdminToolDescriptor.isAppLauncherApplication
API method.