Release Notes for XWiki 8.3

Last modified by Vincent Massol on 2017/09/13

The following important problems were found after this version was released. We recommend using the 8.4.1 release (when it'll be available).

  • Closed XE-1591 Certificate errors are logged with Java version lower than 1.8.0_101 The best is to use the latest version of Java 8 (it's the best in general anyway). However you can check the comments in the issue for possible workarounds if you need to keep using an older version of Java 8.
  • Closed XWIKI-13873 Impossible to translate a page 
  • Closed XWIKI-13871 Navigation links from left panel won't load when "Bac à sable" is selected 

This is the release notes for XWiki Commons, XWiki Rendering, XWiki Platform and XWiki Enterprise. They share the same release notes as they are released together and have the same version.

This release introduces Recommended Extensions both on and inside the Extension Manager. Other changes are page suggestions for non-existing page, exporting child pages in XAR and HTML formats and many more improvements. For developers, we added visibility and creation restrictions on template providers and also Velocity templates can be provided inside a JAR extension.

New and Noteworthy (since XWiki 8.2)

Full list of issues fixed and Dashboard for 8.3.

For Users

Children Macro

A new {{children/}} macro has been added to display a tree view of all children of the current page.

XAR Children Export

It's now possible, for HTML and XAR formats, to export selected children along with the current page.

Ratings on Extensions Repository home page

Rating is now displayed in the Repository App's home page livetable.

Document Tree Improvements

The tree now displays the rendered translated page title when the showDocumentTitle parameter is set to true, which is the default value. So the document tree is now taking into account the current locale when displaying the page titles. Moreover, the child pages are now sorted by their raw translated title, with a fall-back on the raw default title and then on the page name (if the raw titles are empty). Note that the rendered title may be different than the raw title if the title is dynamic (i.e. has Velocity code) so the child pages may not be sorted correctly if some have dynamic titles. The child pages are sorted by their name when the showDocumentTitle parameter is set to false.

The support for relative references in the root and openTo parameters has been improved. You still need to prefix the entity reference with its entity type though.

{{documentTree root="document:Alice" openTo="document:Bob" /}}

The behavior of the limit parameter has changed a bit: if there is only one child node remaining the "more ..." link is replaced by that child node, instead of displaying "one more".

The child nodes should be loaded much faster now as we refactored and improved the database queries used under the hood.

Active Installs for Extensions

The number of active installs is displayed for each extension in the Repository App's home page livetable and in the extension page.

Not Found Suggestions

We have added suggestions for the "document not found" and "attachment not found" error screens. The suggestions address minor typos and misspelling (including lower case vs upper case), but also bad location requests.

Extension Repository adds recommendations

The Extension Repository Application now supports the optional feature of being able to mark some Extensions as Recommended. This provides some form of curation and separate "good" Extensions from others. The need arises when there are lots of Extensions. 

The screenshots show:

  • The view when the Recommendation feature is turned on
  • How a Recommended Extension is displayed with a badge showing it's Recommended

The Blog Category Panel now has an entry for All blog posts with a RSS feed for all.

User Profile Preference Hints

We have added documentation hints for User Profile Preferences so that it's more obvious to understand what each option means.

Improved Not Found Screen

Added partial matches for the Document/Attachment Does Not Exist suggestions, in addition to the existing stemmed and fuzzy matches, for better results.

We were previously searching using indexed Solr data (stemmed) and also using fuzzy searches (string difference of 2; helps with minor typos), but this did not cover partial matches. Example: "Sandb" is matched by the fuzzy search, since it has a difference of 2 characters ("ox"), but "Sand" is not matched by anything (no stemming and too greater string difference - 3).


  • When importing an office document with embedded images, those images are now saved as attachments to the target wiki page. This used to be the default behavior until recent versions of LibreOffice / OpenOffice have started to embed the images in the generated HTML using the Data URI scheme, which ended up in the wiki syntax. We have now restored the initial behavior.

  • New parameters for the Gallery Macro: The Gallery Macro has 3 new parameters. You can use the width and height parameters to control the amount of space reserved for the gallery. The class parameter can be used to add custom CSS class names in order to customize the appearance of a gallery. Here's an example where we use the Bootstrap Grid system:

    {{gallery class="col-xs-12 col-sm-6 col-md-4" width="" height="300px"}}
    image:[email protected]
  • The AutoSave feature is now available in the WYSIWYG edit mode.

For Admins

Display recommended extensions in the Extension Manager

Extension Manager is now displaying only recommended extension by default.

You can still switch to All Remote Extensions. If no recommended extension is can be found for the provided search, the result for All Remote Extensions is displayed.

Global Color Themes

It's now possible, on a subwiki, to use a color theme coming from the main wiki (global themes).

Template Restrictions

It's now possible to specify visibility restrictions separate from creation restrictions on a template provider and to set default values. See the documentation for more details.

Make most expensive steps more visible

The performance tree give interesting information but it was hard to see quickly which steps where causing performances issues.

More details


  • Active installs client now send the memory used by the instance.

  • It's now possible to disable core extension update at startup. See property extension.core.resolve in

  • The Let's Encrypt root certificate is now automatically registered at runtime.

  • Debian packages now override standard configuration files handling for xwiki.cfg, and web.xml to provide 3 ways merge with standard dpkg and apt command line tools.

For Developers

Templates from JARs

TemplateManager component now also search for templates in current Thread classloader which mean you can put your templates inside your JAR in the /templates folder. This is the last step to any JAR extension can provide default template which can be overwritten in a skin on in /template/ WAR resources.

Temporary Resource API

A new API is available to create temporary resources. Here's an example of how you can use it:

// (1) Create the temporary resource reference.
String moduleName = "chart";
List<String> resourcePath = Arrays.asList("pie", "issuesByReporter.png");
EntityReference owningEntityReference = new DocumentReference("wiki", Arrays.asList("Path", "To"), "Page");
TemporaryResourceReference temporaryResourceReference =
   new TemporaryResourceReference(moduleName, resourcePath, owningEntityReference);

// (2) Create the temporary file.
InputStream content = new ByteArrayInputStream("content".getBytes());
File tempFile = this.temporaryResourceStore.createTemporaryFile(temporaryResourceReference, content);

// (3) Obtain the URL that can be used to access the above temporary file.
String temporaryResourceURL =

Author Executor

It's now easier to execute code with a different author. Author is used to check SCRIPT and PROGRAMMING right. Example:, getAuthorReference());

Velocity and ScriptContext synchronization

VelocityContext and ScriptContext are now fully in sync (and if you find a use case where it's not true create a BUG on and VelocityContext is now close to internal detail. This allows for example defining a variable in Velocity and accessing it from a Groovy script:

## Setting some script binding in Velocity
#set($myvar = "toto")

// Lets use the script binding that has been set in previous script
print myvar

More details


  • Two new generic extension points for the Document/Attachment Not Found views:

  • The Velocity #try() directive now accepts an optional parameter to specify the name of a Velocity variable into which to save the caught exception. For example:


    #if ($myexception != '')
      ... do something...
  • Added an order field to the "After Header" extension point.

  • Injected extension repositories can now be associated with a priority

  • It's now possible to customize a Maven repository in with any Aether property. See XWiki Commons - Extension - Repository - Maven.

  • "Recommended" concept has been added to Extension and Repository API

  • Execute Macros in context of another page: The Context Macro now supports executing macros in the context of the referenced document by using the new transformationContext parameter.

    For example the following content generates the screenshot:

    {{context document="Sandbox.WebHome" transformationContext="document"}}
  • A new "instance" ScriptService has been introduced with an API to get the XWiki instance id. New methods will be added if needed. See Instance Module extension for more details.

  • It's now possible to directly create a pre-configured mail Session. See Mail Sender API.

  • uid Reference serializers now supports Locales in DocumentReference. It's added at the end of the string representation, in the same way as for other parts of the reference (same as what XWikiDocument#getKey() was doing).

  • It's now possible to change the socket and connection timeouts of a XWiki Repository in See XWiki Commons - Extension - Repository - XWiki.

  • Two new specific extension points for providing recommendations in the Document/Attachment Not Found views:

  • Filter Stream annotations: Thanks to Java 8 now supporting getting method parameter names through reflection, it's not required anymore to use @Name annotation in the definition of a filter. See Filter Module for more details.

    It's also possible to override the name of the event (which is by default extracted from the method name) using the @Name annotation.

    Filter manager make sure to calculate the event descriptor based on the top most overridden method (usually coming from an interface). Various things were not always properly inherited (like event name or reflection based parameters names).

Moved Modules

  • Cache module has been moved to XWiki Commons. This mostly means that you can now use it in commons and rendering modules. Nothing change in the classes or packages names, just need to update group id and artifact id in your build tool.
  • Application Manager moved to Contrib (, it can still be installed as extension if required



The following translations have been updated: 

  • Catalan
  • German
  • Simplified Chinese
  • Danish
  • Spanish
  • French
  • Latvian
  • Dutch
  • Russian
  • Slovak
  • Swedish
  • Turkish

Tested Browsers & Databases

Here is the list of browsers we support and how they have been tested for this release:

BrowserTest Result
Chrome30.pngGoogle ChromeNot Tested
Firefox30.pngMozilla Firefox 49Jira Tickets Marked as Fixed in the Release Notes + New and Noteworthy Features
IE30.pngInternet Explorer 10Not Tested
IE30.pngInternet Explorer 11Not Tested

Here is the list of databases we support and how they have been tested for this release:

DatabaseTest Result
hypersql.pngHyperSQL 2.3.4Jira Tickets Marked as Fixed in the Release Notes + New and Noteworthy Features
mysql.pngMySQLNot Tested
oracle.pngOracleNot Tested
postgresql.pngPostgreSQLNot Tested

Performances tests compared to 7.4.5


"similar": difference is lower than 10%
"slightly": difference is lower than 20%

Note that most of the speed related values are an average of very moving results, a lot of things is happening during a HTTP request and it's far from stable duration (that's why 10% may sounds a lot for something called "similar" but the variable can go up and down around 5% sometimes so 10% average is really not that much of a clear win). Dumbbench based tests are executed several times and the lowest result is selected. 


Jetty startupslightly slower
First accessnot existing page without UIslightly slower
not existing page with UIsimilar
Reloadnot existing page without UIsimilar
not existing page with UI+27%
empty page without UIsimilar
empty page with UIslightly slower
Main.WebHome without UI/5
Main.WebHome with UI-23%
SOLRFull SOLR reindexsimilar
SOLR sync when index is emptysimilar
SOLR sync when there is nothing to dosimilar
Result of search finding lots of resultssimilar
Result of search finding one resultsimilar
RenderingPage with 1000 macros without UIsimilar
Page with 1000 html macros without UIslightly slower


Heap Memory after jetty startup+24MB
Heap Memory after full SOLR index+29MB

More details on performance comparison on single wiki between 8.3 and 7.4.5.

Known issues

Backward Compatibility and Migration Notes

General Notes

When upgrading make sure you compare your xwiki.cfg, and web.xml files with the newest version since some configuration parameters may have been modified or added. Note that you should add so that XWiki will attempt to automatically migrate your current database to the new schema. Make sure you backup your Database before doing anything.

Issues specific to XWiki 8.3

LDAP Module moved to Contrib

The module containing among other things the standard LDAP authenticator has been moved to and is not embedded anymore in XE. Starting with 8.3M1 you need to install it if you want to use it. See for more details on what is different between the XWiki Platform module and the new Contrib Extension.

If you don't have any "pure" XWiki admin user to install the extension you can use superadmin user. See documentation.

Cache module moved to XWiki Commons

The only thing that changed is the id of the modules. If you have any dependency on those you just need to change org.xwiki.platform:xwiki-platform-* to org.xwiki.commons:xwiki-commons-*

API Breakages

The following APIs were modified since XWiki 8.2.1:

  • Align with ExtensionRepository API
    • Violation type: java.method.exception.checkedAdded
    • Old: method org.xwiki.extension.repository.result.IterableResult<org.xwiki.extension.Extension> org.xwiki.extension.repository.ExtensionRepositoryManager::search(java.lang.String, int, int)
    • New: method org.xwiki.extension.repository.result.IterableResult<org.xwiki.extension.Extension> org.xwiki.extension.repository.ExtensionRepositoryManager::search(java.lang.String, int, int) throws
  • Align with ExtensionRepository API
    • Violation type: java.method.exception.checkedAdded
    • Old: method org.xwiki.extension.repository.result.IterableResult<org.xwiki.extension.Extension> org.xwiki.extension.repository.ExtensionRepositoryManager::search(
    • New: method org.xwiki.extension.repository.result.IterableResult<org.xwiki.extension.Extension> org.xwiki.extension.repository.ExtensionRepositoryManager::search( throws
  • Young API. Remember the external name of the resource
    • Violation type: java.method.addedToInterface
    • Old: null
    • New: method java.lang.String<I extends org.xwiki.filter.input.InputSource>::getResourceName()
  • Young API. Add helpers
    • Violation type: java.method.addedToInterface
    • Old: null
    • New: method org.xwiki.rendering.block.XDOM org.xwiki.template.TemplateManager::execute(org.xwiki.template.Template) throws java.lang.Exception
  • Young API. Add helpers
    • Violation type: java.method.addedToInterface
    • Old: null
    • New: method org.xwiki.rendering.block.XDOM org.xwiki.template.TemplateManager::executeNoException(org.xwiki.template.Template)
  • Young API. Add helpers
    • Violation type: java.method.addedToInterface
    • Old: null
    • New: method org.xwiki.rendering.block.XDOM org.xwiki.template.TemplateManager::getXDOM(org.xwiki.template.Template) throws java.lang.Exception
  • Young API. Add helpers
    • Violation type: java.method.addedToInterface
    • Old: null
    • New: method org.xwiki.rendering.block.XDOM org.xwiki.template.TemplateManager::getXDOMNoException(org.xwiki.template.Template)
  • Young API. Add helpers
    • Violation type: java.method.addedToInterface
    • Old: null
    • New: method void org.xwiki.template.TemplateManager::renderNoException(org.xwiki.template.Template,
  • Align with ExtensionRepository API
    • Violation type: java.method.exception.checkedAdded
    • Old: method org.xwiki.extension.repository.result.IterableResult<org.xwiki.extension.Extension> org.xwiki.platform.flavor.FlavorManager::getFlavors(org.xwiki.platform.flavor.FlavorQuery)
    • New: method org.xwiki.extension.repository.result.IterableResult<org.xwiki.extension.Extension> org.xwiki.platform.flavor.FlavorManager::getFlavors(org.xwiki.platform.flavor.FlavorQuery) throws
  • Align with ExtensionRepository API
    • Violation type: java.method.exception.checkedAdded
    • Old: method org.xwiki.extension.repository.result.IterableResult<org.xwiki.extension.Extension> org.xwiki.platform.flavor.FlavorManager::searchFlavors(org.xwiki.platform.flavor.FlavorQuery)
    • New: method org.xwiki.extension.repository.result.IterableResult<org.xwiki.extension.Extension> org.xwiki.platform.flavor.FlavorManager::searchFlavors(org.xwiki.platform.flavor.FlavorQuery) throws
  • Was publicly exposing internal class
    • Violation type: java.field.typeChanged
    • Old: field org.xwiki.mail.script.AbstractMailScriptService.sessionFactory
    • New: field org.xwiki.mail.script.AbstractMailScriptService.sessionFactory
  • Not an actual breakage. The class has been moved from xwiki-platform-resource-default to xwiki-platform-resource-temporary module, under the same package.
    • Violation type: java.class.removed
    • Old: class org.xwiki.resource.temporary.TemporaryResourceReference


The following people have contributed code to this release (sorted alphabetically):

Alexandru Cotiuga
Denis Gervalle
Ecaterina Moraru (Valica)
Eduard Moraru
Guillaume Delhumeau
Lukas Krejci
Lukas Raska
Manuel Smeria
Marius Dumitru Florea
Michiel Hobbelman
Sergiu Dumitriu
Thibault Clauzier
Thomas Mortagne
Vincent Massol

Created by Vincent Massol on 2016/09/20

Get Connected