Upgrade from LTS 2015 to LTS 2016

For the general upgrade process, see the page Upgrading the Nuxeo Platform.

This chapter highlights some major information about upgrade from Nuxeo Platform LTS 2015 (7.10) to Nuxeo Platform LTS 2016 (8.10). We strongly encourage you to also have a quick read of the upgrade notes.

If you had already upgraded to previous 8.x Fast Track versions, check out the page Upgrade from LTS 2015 following Fast Tracks for upgrade instructions from 8.1 to 8.2, 8.2 to 8.3 or 8.3 to LTS 2016.

Distribution Changes

Nuxeo Server as the Base Distribution and CAP Removal

The Nuxeo Platform distribution has been refactored to separate server-side features and the user interface. As a consequence the user interface is now available in a Nuxeo Package called Nuxeo JSF UI. This package should be installed on the new base distribution of the platform, called Nuxeo Server. Using Nuxeo Server with the Nuxeo JSF UI is the equivalent of the previous CAP distribution.

Thus the following changes in nuxeo-distribution:

Renamed Maven Modules

• nuxeo-distribution-server => nuxeo-nxr-server
• nuxeo-distribution-jsf-ui => nuxeo-nxr-jsf-ui
• nuxeo-distribution-tests => nuxeo-test-dependencies
• nuxeo-distribution-tomcat-wizard-tests => nuxeo-wizard-tests
• nuxeo-distribution-cap-cmis-tests => nuxeo-server-cmis-tests
• nuxeo-distribution-cap-funkload-tests => nuxeo-jsf-ui-funkload-tests
• nuxeo-distribution-cap-gatling-tests => nuxeo-jsf-ui-gatling-tests
• nuxeo-distribution-cap-webdriver-tests => nuxeo-jsf-ui-webdriver-tests
• nuxeo-distribution-tomcat => nuxeo-server-tomcat, no more -nuxeo-cap classifier

Since the CAP distribution has been removed, you also need to replace nuxeo-distribution-cap by nuxeo-nxr-server.

Functional Tests

The default distribution tested in functional tests is now a simple nuxeo-server-tomcat without the nuxeo-jsf-ui package installed.

tools-nuxeo-ftest has been updated for this purpose, see NXBT-1351.

Consequently, if you need to run functional tests against a distribution including the nuxeo-jsf-ui package, you need to specify it explicitly in the itests.xml file:

<property name="mp.install" value="file:${out.dir}/nuxeo-marketplace-jsf-ui-${maven.project.version}.zip" />
...
<target name="XXX">
  <copy todir="${out.dir}">
    <artifact:file key="org.nuxeo.ecm.distribution:nuxeo-marketplace-jsf-ui::zip" />
  </copy>
</target>

Having the following dependency in the pom.xml:

<dependency>
  <groupId>org.nuxeo.ecm.distribution</groupId>
  <artifactId>nuxeo-marketplace-jsf-ui</artifactId>
  <type>zip</type>
  <scope>provided</scope>
</dependency>

See NXP-19790 and NXP-20938 for details.

Impact on Nuxeo Packages

Maven Artifacts

The changes in the Maven artifact names mentioned above must be applied to any pom.xml or assembly.xml file in a Nuxeo package:

• nuxeo-distribution-cap => nuxeo-nxr-server
• nuxeo-distribution-server => nuxeo-nxr-server
• nuxeo-distribution-jsf-ui => nuxeo-nxr-jsf-ui

Target Platform

The default target platform is now the server distribution, so the package.xml file of a Nuxeo package must contain:

<platforms>
  <platform>server-@DISTRIB_VERSION@</platform>
  <platform>server-@DISTRIB_VERSION@-*</platform>
</platforms>

Dependency on nuxeo-jsf-ui

If a Nuxeo package depends on the nuxeo-jsf-ui package at runtime then it needs to be added as a dependency in package.xml:

<dependencies>
  <package>nuxeo-jsf-ui</package>
</dependencies>

Optional Dependencies

If a Nuxeo package can be installed on a server distribution with or without the nuxeo-jsf-ui package, the package.xml file must contain an optional dependency instead:

<optional-dependencies>
  <package>nuxeo-jsf-ui</package>
</optional-dependencies>

In this case the package assembly needs to handle the split of the bundles and libs into the bundles/bundles-jsf-ui/bundles-web-ui and lib/lib-jsf-ui/lib-web-ui directories of the package. See for example marketplace-dam, marketplace-drive, marketplace-quota.

Same thing about the nuxeo-web-ui package.

Package Functional Tests

As mentioned above in the Functional Tests section, if the functional tests of a Nuxeo package need to be run against a distribution including the nuxeo-jsf-ui package, it needs to be specified explicitly in the itests.xml file.

See NXP-20939 for details.

Installation

Requirements

Java JDK 1.8.0_112 is required.

OpenOffice OpenOffice is no longer supported.

LibreOffice LibreOffice minimum version required is 5.x and the soffice program must be added to the PATH environment variable.

ccextractor Nuxeo DAM now requires ccextractor for video closed captions extraction.

Elasticsearch Upgrade

Upgrade Elasticsearch Version

Upgrading Elasticsearch to 2.3.x is required. Please have a look at Elasticsearch breaking changes here.

In order to upgrade your cluster to 2.3.x, please follow these steps.

Update Properties with Dots

As dots (.) are not longer accepted in a property name, we replaced properties like ecm:path.depth by this form ecm:path@depth. So you need to:

1. Drop your index containing properties with dot.
2. Upgrade Elasticsearch cluster + Nuxeo.
3. Re-index your repository. In Nuxeo case, only the index storing documents needs to be re-indexed.

Use Scroll API to Fetch All Documents

NxQueryBuilder.limit(int) won't accept -1 soon due to Elasticsearch changes on index.max_result_window. This parameter is now 10000 by default, which prevent us to set Integer.MAX_VALUE in order to return all documents.

In order to fetch all documents, we recommend you to use the scroll API instead (ElasticSearchComponent.scroll(NxQueryBuilder, long)). All queries made with a -1 as limit will fail unless you update the index.max_result_window setting on ES cluster (highly unrecommended).

See NXP-19194 for details.

Configuration

New Parameters

Parameters to Update

Notes

Stacktraces are now hidden per default in error pages. Activate the dev mode (org.nuxeo.dev=true) to get them back.

Nuxeo Studio Application Definition

Make sure your Nuxeo Studio project depends on the Nuxeo JSF UI target package. See the pages How to Update the Version of Your Target Platform in Studio and Specific Upgrade Instructions for more details.

Code Changes

Deleted APIs

REST endpoint /group/{groupname} no longer marshall members (users and groups) per default. To keep them present in the response, use fetch.group=memberUsers and/or fetch.group=memberGroups properties in the request. See NXP-19112.

Deleted Features

Annotations were removed from Nuxeo Platform 8.2.

Deprecated APIs 

• Calls to Environment.getHome() might need to be replaced with Environment.getRuntimeHome() or Environment.getServerHome() to ensure that you are using the correct home path in your code. See NXP-18667.

• The following methods are deprecated in order to introduce same methods with a var args argument CopyOption. See NXP-19740 for details.
  • CoreSession#copy(DocumentRef, DocumentRef, String)
  • CoreSession#copy(List<DocumentRef>, DocumentRef)
  • CoreSession#copyProxyAsDocument(DocumentRef, DocumentRef, String)
  • CoreSession#copyProxyAsDocument(List<DocumentRef>, DocumentRef)

• Extension point request-configuration of org.nuxeo.ecm.webengine.WebEngineComponent is now obsolete: a transaction will always be started when calling a WebEngine endpoint. NXP-20045

• NuxeoAuthenticationFilter#DEFAULT_START_PAGE has been removed, use LoginScreenHelper.getStartupPagePath() instead. See NXP-19992 for details.

• Compatibility AssetLibrary document type has been removed. You must update your database to change the type from AssetLibrary to Domain. See NXP-20943 for details.

    # PostgreSQL Update Query
    UPDATE hierarchy SET primarytype = 'Domain' WHERE primarytype = 'AssetLibrary';
  

• Framework.getService(CoreSession.class) has been removed. You must use Framework.getService(CoreSessionService.class).createCoreSession(repositoryName, principal) instead. See NXP-20083 for details.

• All DataModel and DocumentPart public APIs have been deprecated, and reserved for internal use:

    Deprecated:
    - DataModel
    - DataModelMap
    - DocumentModel.getDataModelsCollection
    - DocumentModel.getDataModels
    - DocumentModel.getDataModel
  
    Deprecated:
    - DocumentPart
    - DocumentModel.getPart(schema)
    - DocumentModel.getParts()
    New methods:
    - DocumentModel.getPropertyObject(schema, name)
    - DocumentModel.getPropertyObjects(schema)
  

Select2 Operations Moved

The operations used by select2 widgets have been extracted from the nuxeo-platform-ui-select2 bundle to the nuxeo-automation-features one:

• org.nuxeo.ecm.platform.ui.select2.automation.SuggestUserEntries is now org.nuxeo.ecm.automation.core.operations.users.SuggestUserEntries
• org.nuxeo.ecm.platform.ui.select2.automation.SuggestDirectoryEntries is now org.nuxeo.ecm.automation.core.operations.services.directory.SuggestDirectoryEntries

Nuxeo and iframe

Nuxeo is now sending the X-FRAME-OPTIONS header with SAMEORIGIN value. It restricts Nuxeo to be embedded in an iframe from the same origin.

You can disable it using:

<require>org.nuxeo.ecm.platform.web.common.requestcontroller.service.RequestControllerService.defaultContrib</require>

<extension target="org.nuxeo.ecm.platform.web.common.requestcontroller.service.RequestControllerService"
    point="responseHeaders">
  <header name="X-Frame-Options" enabled="false"/>
</extension>

This is required for the addon Nuxeo for Salesforce. See NXP-19629 for details.

WorkManager

The canceled and completed states are removed from the work's API. So you can't get results from completed works anymore. Instead you should store results by means of the transient store. The previous way of querying for queue's counter has been deprecated by a the new API org.nuxeo.ecm.core.work.api.WorkManager.getMetrics(String) which provides you with the consistent set of counters. See NXP-19160 for details.

REST Workflow

The url property of a workflow blob has been moved to the data property. See NXP-19640 for details.

The url property of a blob is now following the correct pattern. Previously ../[thumbnail:thumb:thumbnail/retrievedFile.png](http://thumbnailthumbthumbnail) is now ../[thumb:thumbnail/retrievedFile.png](http://thumbthumbnail). See NXP-18239 for details.

Optimizations

Nuxeo Drive

The permission checks done when adapting a document to a FileSystemItem are optimized by default with the org.nuxeo.drive.permissionCheckOptimized property of the ConfigurationService set to true.

The previous behavior can be re-activated using:

<extension target="org.nuxeo.runtime.ConfigurationService" point="configuration">
  <property name="org.nuxeo.drive.permissionCheckOptimized">false</property>
</extension>

See NXP-19441 for details.

JSF Pages Rendering and Processing

Nuxeo 8.2 and Nuxeo 7.10-HF12 hold changes optimizing performance of JSF pages rendering and processing).

These improvements rely on:

1. Optimizations of variables exposure in the context
2. Optimizations of pluggable actions rendering
3. Optimizations of document listings rendering

Some helpers have also been defined to help analyzing what element is taking time when rendering a page, see How to Debug Slow Page Rendering.

Optimizations 1 and 2 should not have any impact on existing templates, maybe except on edge cases. If the misbehavior is affecting a tag nxu:set, the boolean attribute useAlias=true can be used to get back the old behavior.

Optimization 3 can have an impact on custom widget templates when used inside document listings, as some variables may not be available in the same context: c:set, c:if tags are resolved at build time, they should be replaced by other JSF tags using the rendered attribute, resolved at render time.

Reference JIRA issue: NXP-17690

From Nuxeo versions 9.3, 8.10-HF18 and 7.10-HF34, additional optimizations were done on vocabulary pages, when showing lots of entries, similar to optimizations previously done for document listings rendering.

Reference JIRA issue: NXP-23394

Nuxeo Packages

Code Changes

Nuxeo Digital Signature

Only administrators can use signPDF and signPDFDocument Operations. Otherwise an OperationException is thrown. See NXP-15990 for details.

Nuxeo Live Connect

Several changes in BatchUpdateBlobProvider break compatibility with custom code created on LTS 2015 or before. We removed two public methods only used internally:

• getPageProviderNameForUpdate()
• getBlobProviderId()

The code of BatchUpdateBlobProvider#processDocumentsUpdate() was moved to an abstract class AbstractLiveConnectBlobProvider which provides a default implementation above interface.

To upgrade your code:

1. Make your classes to extend AbstractLiveConnectBlobProvider which provides implementation of BatchUpdateBlobProvider.
2. Remove call to getBlobProvider() or implement it in your custom code. See NXP-18660.

Nuxeo Multi Tenant

We removed multi_tenant_user.xsd and multi_tenant_group.xsd schemas. The tenantId field is now part of default user.xsd and group.xsd schemas. See NXP-18496.

New Packages

The Nuxeo JSF UI package lets you install theNXP-19740 Nuxeo UI based on JSF technologies.

Deprecated Packages

The following addons are deprecated with the release of Nuxeo Platform LTS 2016:

• Nuxeo Review Workflows Dashboards
• Smart Search
• Nuxeo Virtual Navigation
• Nuxeo Forum

nuxeo-web-mobile has been deprecated in order to let some place to the new standalone Nuxeo Application, available on iOS and Android.

Complementary Information

Upgrade notes:

• Upgrade notes for LTS 2016
• Upgrade notes for 8.3
• Upgrade notes for 8.2
• Upgrade notes for 8.1

Release notes:

• Release notes for LTS 2016
• Release notes for 8.3
• Release notes for 8.2
• Release notes for 8.1