This feature allows you to export one or several pages from your wiki into a XAR file (XWiki ARchive) or to import one or several pages from an existing XAR file. This is useful for moving wiki pages from one instance to another or to perform lightweight backup of your wiki pages.

This feature doesn't replace a proper backup.

Importing XWiki pages

Prerequisites:

  • New in XWiki 5.0+ If your wiki is empty and this is your first import, you will need to log in as superadmin to do the first import since there are no users defined in the wiki at this time.
  • A configured database and Servlet Container. If you don't have them, see the Installation guide.

Follow these steps:

  • Ensure your database and container are started
  • Point your browser to http://localhost:8080/xwiki/bin/admin/XWiki/XWikiPreferences or click on the "Wiki" menu and then on "Administer Wiki"
  • Click on "Import"
  • Attach the XAR file you wish to import and then select it from the list under "Available packages". After a few seconds you should see the list of all the pages in your XAR listed and selected by default (unselect the pages/folders you don't wish to import):

    ImportPackageFlamingo.png

  • Select the second radio button if you want to replace the document history with the history from the imported package. If you don't select it the newly imported pages will have the revision "1.1"
  • Click "Import". This will import all the selected pages
  • At this stage your rights might have been changed as the import may have imported different rights. You may need to log out and log in again.

If you own the sub-wiki (virtual wiki, wiki-farm), you need to be sure that you either:

  • install with a global user having Programming Rights (PR) and UNCHECK the backup pack option
  • install with a global user having PR and keep the backup pack option but in this case MAKE SURE that the user defined in the XAR exists and has PR.
    Otherwise all imported pages would be saved without PR and scripts won't work until you resave them under the user with Programming Rights .

Note, that pages requiring PR are supposed to also contain a XWiki.RequiredRightClass xobject so it should be easy to query them. If you find some that don't have this XObject please let us know. This XObject is just indicative and doesn't change permissions.

If you get a 'Java heap space Out Of Memory exception' you'll need to increase the memory allocated to the JVM running XWiki. How you do this depends on the container you use:

  • For Jetty you must change a line in start_xwiki.bat (or start_xwiki.sh) from JAVA_OPTS=-Xmx300m to something like JAVA_OPTS=-Xmx1024m
  • For Tomcat you must set CATALINA_OPTS to something like -Xmx1024m

Importing an Extension

When you import a XAR, if the XAR's package.xml contains an extensionId value (representing an Extension Id) then the Importer will check if the Extension exists in its configured XWiki Extension Repositories (the configuration for this is located in xwiki.properties under the extension.repositories keys). If the Extension is found, the Importer will then register it in the list of installed Extensions that you can see when going to the Extension Manager Application's UI.

Exporting XWiki pages

Prerequisites:

  • A configured database and Servlet Container. If you don't have them, see the Installation guide.

Follow these steps:

  • Ensure your database and container are started
  • Point your browser to http://localhost:8080/xwiki/bin/admin/XWiki/XWikiPreferences
  • Click "Export" and fill the form
  • Click "Export"

    ExportPackageFlamingo.png

Customizing a XAR

When doing an export, XWiki pages are saved using the XAR format. A typical XAR created when doing an export will include all the pages on your XWiki instance. However you can control this using a custom Export URL.

That said, it is also possible to create a XAR that will include only the pages you want. This is useful when you want to export only the pages of a specific application for example. Here are the steps:

  • Unzip the file
  • Keep the pages you want to put in your archive
  • Edit package.xml to delete the pages you do not want to be in the archive
  • Zip together the modified package.xml file and the pages you want to put together in your archive, naming the file "MyArchive".xar where "MyArchive" is the actual name you want to give it
  • You're done! You can now import this specific set of pages to any XWiki instance

In the future XWiki will offer the ability to do selective exports natively. For the moment you'll need to install the Multipage Export Extension.

XAR Format

Definition of the XAR format version 1.1

A XAR file is a ZIP file containing the following:

  • A package.xml file acting as the XAR descriptor and containing metadata. Example:
    <?xml version="1.0" encoding="UTF-8"?>

    <package>
     <infos>
       <name>XWiki Platform - Panels - UI</name>
       <description>Panels and Panel Wizard to easily create menus for XWiki</description>
       <licence></licence>
       <author>XWiki.Admin</author>
       <extensionId>org.xwiki.platform:xwiki-platform-panels-ui</extensionId>
       <version>7.1-SNAPSHOT</version>
       <backupPack>false</backupPack>
       <preserveVersion>true</preserveVersion>
     </infos>
     <files>
       <file language="" defaultAction="0">Panels.Applications</file>
       <file language="" defaultAction="0">PanelsCode.ApplicationsPanelConfiguration</file>
       <file language="" defaultAction="0">Panels.EditTranslations</file>
       <file language="lv" defaultAction="0">PanelsCode.Translations</file>
       <file language="pt_BR" defaultAction="0">Panels.Translations</file>
       <file language="fr" defaultAction="0">Panels.Translations</file>
     </files>
    </package>
  • A list of XML files representing wiki pages. Each fil is located in a directory named after the Wiki space it is in. Note that this XML format is the format you get when you use the xpage=xml parameter when on wiki page URL.

The format of package.xml is as follows:

  • name: name representing what's contained in the XAR
  • description: more detailed description of the content of the XAR
  • license: can be set to specify under which license this XAR content is published
  • author: Wiki author of this XAR. This is important. When the XAR is going to be imported this is the author that it'll be imported with if the "import as backup pack" option is selected at import time
  • extensionId (optional): if set then this marks the XAR as containing an Extension. Thus when you import it, the Extension Manager will be able to match it with its Extension database and perform versioning verifications.
  • preserveVersion (optional): if set to true then the history is preserved (the history for each page is part of its XML)
  • backupPack: if true it means that the XAR is a backup pack. It's up to the import to decide whether to import it as a backup pack or not but this provides the information that it is a backup pack.

The format of the file element is as follows:

  • language: the language of the page. The default page content should use an empty string.
  • defaultAction: This is unused.
  • The value inside the file element is the reference of the page, relative to the current wiki (i.e. Space.Page)
Tags:
Created by Vincent Massol on 2006/12/12
   

Get Connected