arrow-down
    1. Widgets
    1. ID providers
    2. System ID provider
    3. Users and groups
    4. Roles
    1. Projects
    2. Layers
        1. AttachmentUploader
        2. Checkbox
        3. Combobox
        4. ContentSelector
        5. ContentTypeFilter
        6. CustomSelector
        7. Date
        8. DateTime
        9. Double
        10. GeoPoint
        11. HtmlArea
        12. ImageSelector
        13. Long
        14. MediaSelector
        15. Radiobutton
        16. Tag
        17. TextArea
        18. TextLine
        19. Time
      1. Field set
      2. Item set
      3. Option set
      4. Mixins
      5. Localization
    3. Content Types
    4. X-data
    5. Macros
    6. Custom styles
    7. Sites
      1. Regions
      2. Part component
      3. Layout component
      4. Text component
      5. Fragments
      6. Filtering
      7. Component indexing
      8. Visual editor
    8. Page templates
  1. Applications
    1. Sandboxes
    2. Code
    3. Building
    4. Configuration
    5. TypeScript
      1. Controllers
      2. Globals
      3. HTTP
      4. Events
      5. Error handler
      6. Filters
      7. ID provider
      8. Tasks
      9. Templating
      10. Localization
      11. Websocket
      12. Mappings
      13. Components
      14. Processors
      15. Contributions
      16. Main controller
      17. Java bridge
      1. Admin API
      2. Application API
      3. Auditlog API
      4. Authentication API
      5. Cluster API
      6. Common API
      7. Content API
      8. Context API
      9. Event API
      10. Export API
      11. Grid API
      12. I18N API
      13. IO API
      14. Mail API
      15. Node API
      16. Portal API
      17. Project API
      18. Repo API
      19. Scheduler API
      20. Schema API
      21. Tasks API
      22. Value API
      23. VHost API
      24. Websocket API
      1. Webapp Engine
        1. Image service
        2. Component service
      2. Admin Engine
      3. Asset service
      4. HTTP service
      5. IDprovider service
    1. Task engine
    2. Management Endpoint
    3. Statistics Endpoint
    1. Nodes and repos
    2. Properties
    3. Indexing
    4. Branches
    5. Queries (NoQL)
    6. Queries (DSL)
    7. Filters
    8. Aggregations
    9. Highlighting
    10. Editors
    1. Strategies
    2. Distributions
    3. Docker image
    4. Vhosts
    5. Configuration
    6. Backup & restore
    7. Systemd
    8. Clustering
  2. Audit Logs
    1. Upgrade Notes
    2. Upgrading Apps

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 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 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

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:

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. APIs 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.

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 to jakarta.servlet

  • javax.mail to jakarta.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.

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.


Contents

Contents

AI-powered search

Juke AI