Release Notes for XWiki 7.1

Last modified by Thomas Mortagne on 2023/10/13

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 adds important changes and improvements for Extension Manager, Solr Search, Watchlist, a new experimental Flavors mechanism and a Debug mode for performance analysis. 

This release introduces a bug concerning the upgrade of the subwikis (XWIKI-12208). You can still upgrade them via Distribution Wizard but only at the same time you upgrade the main wiki. You can also upgrade your subwiki's UI like any other extensions, by clicking on "Check for updates".

The best is to wait for the release of 7.1.1 which will fix this problem and should be ready really soon.

Extension Manager provides a summary for the extension diff view in order to ease the navigation of the local code changes. A new Extension History section has also been added, offering support for selective export, import and replay of extension-related history records. 

Solr Search UI is improved by making it responsive on small screens. The users can now sort, paginate and filter the search results without a page reload. 

The Flavors and Watchlist Realtime option are currently still experimental, but you are encouraged to test them and provide feedback. 

The WatchList performance has been improved, especially for the Realtime notification option. The Realtime Watchlist messages are displayed in a more user-friendly way, sending mails for a variety of events, threaded by your email client by the document they occurred in.

The Flavor mechanism is allowing the selection of Flavors in the wiki creation step. In the future, XWiki will offer different Flavors and these are steps towards this direction.

Under-the-hood there are various mail and job module improvements. The developers can now trigger old Prototype event listeners from jQuery and a new API is available to escape wiki syntax.

New and Noteworthy (since XWiki 7.0)

Full list of issues fixed and Dashboard for 7.1.

Extension Manager

Diff View Summary

Since XWiki 7.0RC1 you can view the local changes that have been made to the wiki pages of an installed extension. In this release we have improved the diff view by adding a summary that will help you navigate the changes.

extensionDiffViewSummary.png

Extension History

The Extension Manager Application has a new section that shows the history of the extension-related actions (e.g. install, uninstall, repair, etc.) offering support for selective export, import and replay of history records. This basically means that an administrator can:

  • keep track of the extensions that are installed/uninstalled on his wiki (see who performed the action and when, in reverse chronological order, most recent first)
  • perform a couple of actions (e.g. install/upgrade a group of extensions) on a single wiki and then replay those actions on multiple wikis

extensionHistorySources.png

Replay an Upgrade

Using the new Extension History section you can record an upgrade performed with the Distribution Wizard and replay it on a different wiki. Check out the Distribution Wizard documentation for more details.

See the Extension Manager Application for more details.

Solr Search

  • We worked on making the search UI responsive on small screens. On mobile phones the list of search facets is now collapsed above the search results and the user can toggle it with a tap. We improved the way the search results of type Object and Object Property are displayed (check the result title and location / breadcrumb). We switched to using the icon themes for the search result icons and we also fixed some small spacing and alignment issues introduced by the migration from the old Colibri skin to the new Flamingo skin. Last but not least, we worked on refreshing the search UI without reloading the entire page when the user sorts the search results, uses the pagination or drills down the results using the search facets.

    searchPageMobile.png

  • It's now possible to disable highlighting and faceting which are very slow tasks. Can be controlled directly from the search UI or from the Main.SolrSearchConfig document.

    solr_options.png

See the Solr Search Application documentation for more details.

Watchlist

The Realtime option is currently experimental and disabled by default.

  • The WatchList application now uses the new Mail API instead of the old and deprecated Mail Plugin.
  • The WatchList Realtime notification option has been reworked and the previous performance penalty has been removed.
  • A new option was added to Watch a page that was just shared by mail directly from the email's body.

      share-footer-actions-watch.png

  • The realtime watchlist messages are now handled separately from the schedules (hourly, daily, weekly) notifications. We have a separate template for them and, because of this, can now display them in a more user-friendly way and they can be threaded/grouped by your email client by the document they occurred in. For more information and screenshots, please see the documentation.

    watchlistRealtimeChangesMailConversation.png

  • Running multiple XWiki instances on the same machine is now possible without affecting WatchList's realtime email threading/grouping. See the documentation for more details.

See the Watchlist Application documentation for more details.

Flavors

This feature is experimental and not bundled in XWiki by default. However, you can install and try it, but only for test purpose.

  • In the future, XWiki will offer different Flavors. A Flavor is a collection of applications. When you install a Flavor, you get a wiki fully configured for a use-case. In this release, we have implemented the ability to chose a Flavor when you create a new wiki.

      createwiki-flavors.png

See the Flavor Module documentation for more details.

Debug mode

It's now possible to display various information about what happens during a request like the time spent on each step and sub steps.
The debug performance tree has been made a bit more dynamic to be able to open/close nodes.

elapsedtimetree2.png

Miscellaneous

  • The Script Macro has been improved to return any type of value even no binding is used to output content.
  • The default Java version triggered as dependency for the Debian packages is now Java 8
  • In the Administration Application, when you change the space you are administrating, you don't lose the current section anymore (if the current section exists in that space).

      administration-change-space.png

  • In edit mode, Password fields do not display the obfuscation placholder (*******) anymore when the password value is empty. For example this removes the confusion when editing the Mail Admin UI and users were thinking that the SMTP Server password was set.
  • Not existing document won't end up in the document cache anymore. That mean request lots of not existing document won't ditch "real" documents from the cache anymore.
  • In App Within Minutes Application, the newly created applications don't have 'App Within Minutes' as parent, but the home page of the current wiki and their home page title doesn't contain the word 'Home' any more.
  • The default document cache size has been increased from 100 to 500 elements
  • Minor visual consistency improvement of the tag cloud header of the LiveTable

See the full list of JIRA issues fixed in this release.

For Developers

Trigger Prototype Event Listeners from jQuery

The event listeners registered from Prototype are now notified when a custom XWiki event is fired using the jQuery API.

// Prototype (old code that you don't have time to rewrite)
document.observe('xwiki:dom:updated', function(event) {
  event.memo.elements.each(function(element) {
   // Do something.
 });
});
...
// jQuery (new code, in a different file/page)
require(['jquery', 'xwiki-events-bridge'], function($) {
  $(document).trigger('xwiki:dom:updated', {'elements': $('.some-container').toArray()});
});

See the developer's guide for more details.

Integration tests for JavaScript with Jasmine + RequireJS + WebJars

Using Jasmine, we have written a few integration tests for JavaScript code that uses AMD (RequireJS) and that has dependencies packaged as Webjars. We found out that the Jasmine Maven Plugin has support for both AMD and WebJars. You can check out this commit to see how we configured the plugin in case you want to write similar tests for your extension or module.

Mail API Improvements

  • Send prepared mime message to multiple users as independent message. A new mime message cloning factory (hint "message") is available to be used with iterator factories. It duplicates a given source message as is, to allow sending it to multiple users as independent messages. See Example 5 of the documentation for a sample.
  • Mail API has been slightly modified to fix a bug when waiting for all mails to have been processed (the waitForProcessing() wasn't really waiting!). As a consequence calls to MailResult.waitTillProcessed(long timeout) and MailResult.isProcessed() have been replaced by calls to MailStatusResult.waitTillProcessed(long timeout) and MailStatusResult.isProcessed(). Note that for backward compatibility reason the scripting API still supports the old API (but it's deprecated and you should move your code to use the new API).
  • Mail Status Store API has been refactored to provides ordered result based on any status fields. A new method also ease loading a single status for a given messageId.
  • When evaluating Velocity in Mail Templates, the Execution Context used is a clone of the one that was available when the send*(...) method was called. Thus all Velocity bindings that were present are available from your Mail Template.

Several API breakages have been introduced, make sure to check the Mail backward-compatibility section below.

Job Progress Improvements

It's now possible to associate message to each step of the progress. Also a new API have been added to make easier to notify about progress in scripts.
See http://extensions.xwiki.org/xwiki/bin/view/Extension/Job+Module#HNotifyaboutprogress for more details.

The progress is now a tree of step with an associated message and elapsed time for each one which can be retrieved during or after the progress is done. It's also automatically serialized in jobs statuses.

Script oriented advanced extension search API

A new script oriented API has been added to use advanced extension search possibilities introduced in 7.0. See Extension Script Module.

Record and Replay Extension Actions

The Extension Module has a new script service to access the extension history and to replay recorded history actions. The extension history records the extension related jobs (e.g. install, uninstall, etc.) along with the decisions taken by the user during the job execution (e.g. merge conflicts, delete unused pages). This means for instance that you can replay an upgrade without the need to handle again the merge conflicts.

The recording is performed by listening to the job events fired during the execution of an extension action, including the new QuestionAskedEvent and QuestionAnsweredEvent introduced in this release.

Miscellaneous

  • The XAR plugin's verify mojo has been improved to allow passing a list of regexes to identify content and technical pages. For example:
    <plugin>
     <groupId>org.xwiki.commons</groupId>
     <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
    ...
     <configuration>
    ...
       <!-- Consider all pages named *Translations as content pages by default -->
       <contentPages>
         <contentPage>.*Translations\.xml</contentPage>
       </contentPages>
       <!-- The EditTranslations page is not a Translation page and thus not a content page! -->
       <technicalPages>
         <technicalPage>EditTranslations\.xml</technicalPage>
       </technicalPages>
     </configuration>
    </plugin>
  • New $services.rendering.escape($content, $syntax) method to escape XWiki syntax. See the documentation.
  • The HTML5 renderer is now bundled in XWiki Enterprise.
  • Added a new objectPolicy=updateOrCreate parameter to the save action that allows editing and creating objects in one request. For more details, see the documentation.
  • It is now possible to select the output syntax of a skin, in order to use the correct renderer.
  • Ability to register a custom Resource Type.
  • The WebJar integration now registers a webjar URL type using a Resource Handler (it was reusing the bin URL type before). The new WebJAR URL format is:
    http://<server>/<context path>/webjars/<path/to/resource>[?version=<version>&evaluate=true|false]

    Note that you should use the exposed Script Service method to compute a WebJAR URL.

  • The mime type of uploaded attachment is now automatically stored in the database and won't be recalculated each time it's asked. Also a new API has been introduced in com.xpn.xwiki.doc.XWikiAttachment to change it if needed.
  • The ConfigurableClass mechanism now supports adding field hints / descriptions. See the documentation.
  • The xwiki-platform-legacy-crypto-script legacy module has been removed as it was conflicting with the Bouncy Castle 1.52 upgrade and we considered that there was little chance that this module was used anywhere in any extension. If by chance (so to speak) you were using it, you'd need to use the newer xwiki-platform-crypto-script module and rebuild your extension with it.
  • Added advanced search support to org.xwiki.extension.repository.ExtensionRepositoryManager
  • The Velocity macros from the Main.SolrSearch page have been moved to a separate page, Main.SolrSearchMacros, which should ease the creation of a custom search page (e.g. if you want reuse some macros and to overwrite others).
  • Added callable support to JobProgressManager. See Job Module.
  • Extension upgrade plan job now support checking specific list of installed extensions (instead of the top level installed extensions)
  • You can now disable the automatic start of Distribution Wizard with two new options.
  • It's possible to disable minification from xwiki.properties configuration file. Set debug.minify to false.

Upgrades

The following dependencies have been upgraded:

Translations

The following translations have been updated: 

Tested Browsers & Databases

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

BrowserTest Result
Chrome30.pngGoogle Chrome 41Not Tested
Firefox30.pngMozilla Firefox 38Jira Tickets Marked as Fixed in the Release Notes
IE30.pngInternet Explorer 8Not Tested
IE30.pngInternet Explorer 9Not Tested

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

DatabaseTest Result
hypersql.pngHyperSQL 2.3.2Jira Tickets Marked as Fixed in the Release Notes
mysql.pngMySQL 5.6.24Not Tested
oracle.pngOracle 11.2Not Tested
postgresql.pngPostgreSQL 9.4.1Not Tested

For the full list of tests see this page.

Performances tests compared to 6.4.4

In this version the performances work concentrated mostly on very low level code like the rendering Blocks manipulation, the html macro and context based component managers. This made the rendering of pages with a lot of macros or macros in the middle of a lot of blocks much faster.

On the bad news it looks like we use more memory than we used to.

Summary

Speed

ActionsDifference
Jetty startupsimilar
First accessnot existing page without UIsimilar
not existing page with UI20% quicker
Reloadnot existing page without UIsimilar
not existing page with UIslightly better
Main.WebHome with UIslightly better
Main.WebHome without UIslightly better
SOLRFull SOLR reindexsimilar
SOLR sync when index is emptysimilar
SOLR sync when there is nothing to dosimilar
Result of search finding lots of results30% quicker
Result of search finding one result20% quicker
RenderingPage with 1000 macros without UI/40
Page with 1000 html macros without UI/8

Memory

ActionsDifference
Heap Memory after jetty startupsimilar
Heap Memory after full SOLR indexhigher

More details on performance comparison on single wiki between 7.1 and 6.4.4.

Known issues

Backward Compatibility and Migration Notes

General Notes

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

Mail API changes

The young mail API has been refactored to provide better and more detailed error reporting. 

The MailState enumeration has been extended to report more detailed mail state (prepare_success, prepare_error, send_success, send_error and send_fatal_error). The MailListener interface has been extended to provide more detailed event. Now each mail batch should use new independent listener. The listener receive the batch identifier of its own batch when the mail preparation starts (#onPrepareBegin()), and have to keep it for all subsequent events. Independent success and error events for both the prepare and send phases are provided for each message (#onPrepareMessageSuccess(), #onPrepareMessageError(), #onSendMessageSuccess(), #onSendMessagError()). Moreover, premature interruption of the prepare phase is caught and reported (#onPrepareFatalError). Inability of the send phase to retrieve a message for sending is also explicitly reported (#onSendMessageFatalError()).

There is now more than one message state representing an error, therefore, the MailStatusResult interface has been extended with a #getAllError() method to retrieve all message status in error. Moreover, the #getTotalMailCount()# may represent a partial total in case of failure of the prepare phase. In that case, it represents the number of mails sent to the send phase. As a consequence, #isProcessed()# and #waitTillProcess()# now considerer the batch to be processed when all successfully prepared mail has been sent, or failed to be prepared or sent.

Please review the new way to check for errors.

The mail API is now tracking individual message based on the standard Message-ID headers, which made it fully compliant with RFC-822 WRT the mail identification. Caller that want to specify custom Message-ID may do so by extending MimeMessage to preserve the Message-ID of the message. Caller is also responsible to ensure that different messages are identified by unique message identifier.

Sending multiple messages with the same Message-ID is no more supported since it does not respect the RFC-822 standard. 

Reusing the same Message-ID for retrying a failed message is allowed and will be tracked by the same status if the batch identifier is also reused.

API Breakages

The following APIs were modified since XWiki 7.0.1:

  • Add support for advanced search
    org.xwiki.extension.repository.ExtensionRepositoryManager: Method 'public org.xwiki.extension.repository.result.IterableResult search(org.xwiki.extension.repository.search.ExtensionQuery)' has been added to an interface
  • Add support for named steps
    org.xwiki.job.event.status.JobProgress: Method 'public org.xwiki.job.event.status.JobProgressStep getCurrentStep()' has been added to an interface
    org.xwiki.job.event.status.JobProgress: Method 'public org.xwiki.job.event.status.JobProgressStep getRootStep()' has been added to an interface
    org.xwiki.job.event.status.JobProgressManager: Method 'public void endStep(java.lang.Object)' has been added to an interface
    org.xwiki.job.event.status.JobProgressManager: Method 'public void pushLevelProgress(java.lang.Object)' has been added to an interface
    org.xwiki.job.event.status.JobProgressManager: Method 'public void startStep(java.lang.Object)' has been added to an interface
    org.xwiki.job.event.status.JobProgressManager: Method 'public void startStep(java.lang.Object, java.lang.String)' has been added to an interface
    org.xwiki.job.event.status.JobProgressManager: Method 'public void startStep(java.lang.Object, java.lang.String, java.lang.String, java.lang.Object[])' has been added to an interface
    org.xwiki.job.event.status.JobProgressManager: Method 'public void startStep(java.lang.Object, org.xwiki.logging.Message)' has been added to an interface
  • Add new helper
    org.xwiki.job.event.status.JobProgressManager: Method 'public java.lang.Object call(java.util.concurrent.Callable, java.lang.Object)' has been added to an interface
    org.xwiki.job.event.status.JobProgressManager: Method 'public java.lang.Object call(java.util.concurrent.Callable, int, java.lang.Object)' has been added to an interface
  • Add a new method to this young API
    org.xwiki.skin.Skin: Method 'public org.xwiki.rendering.syntax.Syntax getOutputSyntax()' has been added to an interface
  • Not really been removed but now return Object. Breaks code building that use this method but should be ok for runtime.
    com.xpn.xwiki.XWiki: Method 'public com.xpn.xwiki.render.XWikiRenderingEngine getRenderingEngine()' has been removed
  • Not used since a long time now (XWikiRenderingEngine is a component) and impossible to implement it without a trigerring most of the old rendering engine.
    com.xpn.xwiki.XWiki: Method 'public void setRenderingEngine(com.xpn.xwiki.render.XWikiRenderingEngine)' has been removed
  • Young API. Added handling of URL parameters
    org.xwiki.url.ExtendedURL: In method 'public ExtendedURL(java.net.URL)' the number of arguments has changed
  • Never supposed to be an API
    com.xpn.xwiki.plugin.scheduler.StatusListener: Class com.xpn.xwiki.plugin.scheduler.StatusListener removed
  • Young API. Remove useless Session argument since the MimeMessage will be given a valid Session when it's deserialized from the mail content store for sending.
    org.xwiki.mail.MimeMessageFactory: In method 'public java.lang.Object createMessage(javax.mail.Session, java.lang.Object, java.util.Map)' the number of arguments has changed
  • Young API. Allow load a single message status and added sorting capabilities for multiple statuses.
    org.xwiki.mail.MailStatusStore: In method 'public java.util.List load(java.util.Map, int, int)' the number of arguments has changed
    org.xwiki.mail.MailStatusStore: Return type of method 'public java.util.List load(java.util.Map, int, int)' has been changed to org.xwiki.mail.MailStatus
    org.xwiki.mail.MailStatusStore: Method 'public java.util.List load(java.util.Map, int, int, java.lang.String, boolean)' has been added to an interface
  • Young API. Added explicit batchId argument to stop storing batchId in mime headers.
    org.xwiki.mail.MailContentStore: In method 'public void save(javax.mail.internet.MimeMessage)' the number of arguments has changed
    org.xwiki.mail.MailStatus: In method 'public MailStatus(javax.mail.internet.MimeMessage, org.xwiki.mail.MailState)' the number of arguments has changed
  • Young API. Improve states and listener to provide more detailled and better reporting.
    org.xwiki.mail.MailListener: Method 'public void onError(javax.mail.internet.MimeMessage, java.lang.Exception, java.util.Map)' has been removed
    org.xwiki.mail.MailListener: Method 'public void onPrepare(javax.mail.internet.MimeMessage, java.util.Map)' has been removed
    org.xwiki.mail.MailListener: Method 'public void onPrepareBegin(java.lang.String, java.util.Map)' has been added to an interface
    org.xwiki.mail.MailListener: Method 'public void onPrepareEnd(java.util.Map)' has been added to an interface
    org.xwiki.mail.MailListener: Method 'public void onPrepareFatalError(java.lang.Exception, java.util.Map)' has been added to an interface
    org.xwiki.mail.MailListener: Method 'public void onPrepareMessageError(javax.mail.internet.MimeMessage, java.lang.Exception, java.util.Map)' has been added to an interface
    org.xwiki.mail.MailListener: Method 'public void onPrepareMessageSuccess(javax.mail.internet.MimeMessage, java.util.Map)' has been added to an interface
    org.xwiki.mail.MailListener: Method 'public void onSendMessageError(javax.mail.internet.MimeMessage, java.lang.Exception, java.util.Map)' has been added to an interface
    org.xwiki.mail.MailListener: Method 'public void onSendMessageFatalError(java.lang.String, java.lang.Exception, java.util.Map)' has been added to an interface
    org.xwiki.mail.MailListener: Method 'public void onSendMessageSuccess(javax.mail.internet.MimeMessage, java.util.Map)' has been added to an interface
    org.xwiki.mail.MailListener: Method 'public void onSuccess(javax.mail.internet.MimeMessage, java.util.Map)' has been removed
    org.xwiki.mail.MailState: Removed field FAILED
    org.xwiki.mail.MailState: Removed field READY
    org.xwiki.mail.MailState: Removed field SENT
  • Young API. Large refactoring for adding the ability to register new URL Resource Types
    org.xwiki.resource.AbstractResourceReference: Parameter 2 of 'public void addParameter(java.lang.String, java.lang.String)' has changed its type to java.lang.Object
    org.xwiki.resource.ResourceReference: Parameter 2 of 'public void addParameter(java.lang.String, java.lang.String)' has changed its type to java.lang.Object
    org.xwiki.resource.ResourceReferenceHandlerManager: Method 'public boolean canHandle(java.lang.Object)' has been added to an interface
    org.xwiki.resource.ResourceReferenceResolver: Removed field TYPE_URL
    org.xwiki.resource.ResourceReferenceResolver: In method 'public org.xwiki.resource.ResourceReference resolve(java.lang.Object, java.util.Map)' the number of arguments has changed
    org.xwiki.resource.ResourceType: Method 'public org.xwiki.resource.ResourceType fromString(java.lang.String)' has been removed
  • Young API. This method should not have been public from the start
    org.xwiki.mail.script.AbstractMailScriptService: Accessibility of method 'public org.xwiki.mail.script.ScriptMailResult sendAsynchronously(java.lang.Iterable, org.xwiki.mail.MailListener, boolean)' has been decreased from public to protected
  • Young API. Rename MimeMessageWrapper into ScriptMimeMessage (not a wrapper anymore). Velocity scripts are not affected by the change.
    org.xwiki.mail.script.MailSenderScriptService: Return type of method 'public org.xwiki.mail.script.MimeMessageWrapper createMessage(java.lang.String, java.lang.Object, java.util.Map)' has been changed to org.xwiki.mail.script.ScriptMimeMessage
    org.xwiki.mail.script.MailSenderScriptService: Return type of method 'public org.xwiki.mail.script.MimeMessageWrapper createMessage(java.lang.String, java.lang.Object)' has been changed to org.xwiki.mail.script.ScriptMimeMessage
    org.xwiki.mail.script.MailSenderScriptService: Return type of method 'public org.xwiki.mail.script.MimeMessageWrapper createMessage()' has been changed to org.xwiki.mail.script.ScriptMimeMessage
    org.xwiki.mail.script.MailSenderScriptService: Return type of method 'public org.xwiki.mail.script.MimeMessageWrapper createMessage(java.lang.String, java.lang.String)' has been changed to org.xwiki.mail.script.ScriptMimeMessage
    org.xwiki.mail.script.MailSenderScriptService: Return type of method 'public org.xwiki.mail.script.MimeMessageWrapper createMessage(java.lang.String, java.lang.String, java.lang.String)' has been changed to org.xwiki.mail.script.ScriptMimeMessage
    org.xwiki.mail.script.MimeMessageWrapper: Class org.xwiki.mail.script.MimeMessageWrapper removed
  • Young API. Change of API to fix bug in waitForProcessin(). Scripting API has not been broken, only the Java API has
    org.xwiki.mail.MailResult: Method 'public boolean isProcessed()' has been removed
    org.xwiki.mail.MailResult: Method 'public void waitTillProcessed(long)' has been removed
    org.xwiki.mail.MailStatusResult: Method 'public long getProcessedMailCount()' has been added to an interface
    org.xwiki.mail.MailStatusResult: Method 'public long getSize()' has been removed
    org.xwiki.mail.MailStatusResult: Method 'public long getTotalMailCount()' has been added to an interface
    org.xwiki.mail.MailStatusResult: Method 'public boolean isProcessed()' has been added to an interface
    org.xwiki.mail.MailStatusResult: Method 'public void waitTillProcessed(long)' has been added to an interface
    org.xwiki.mail.MailStatusResult: Method 'public java.util.Iterator getAllErrors()' has been added to an interface
  • Young API. Class moved to the "script" package. Script service usage is unchanged.
    org.xwiki.mail.MailStorageScriptService: Class org.xwiki.mail.MailStorageScriptService removed
Tags:
   

Get Connected