Office Importer Application
 | Import Office documents, spreadsheets and presentations into wiki pages (most major office suite formats are supported) |
| Type | XAR |
| Category | |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
| Compatibility |
Table of contents
Description
The Office Importer Application allows users to easily import Office documents like Word documents, spreadsheets and PowerPoint presentations into wiki pages.
The Office Importer features include:
- Convert existing documents into wiki pages
- Use common office suites as wiki authoring tools
How to use
Once XWiki is configured correctly (and the Libre Office server is started), the Office Importer can be used in 2 ways.
Create Page from Office
When creating a new page fill the page name and select the special "Page from Office" page type then click on Create.
You'll be taken to the Office Importer form where you can specify the office file to import and some options that control how the content will be imported.
The following fields are available:
- Office document: allows you to upload the office document to import
- Target page: (read-only) shows where the content will be imported
- Overwrite existing content: shown only when the target wiki page exists already, allows you to control whether to overwrite or not its content
- Filter styles: strip out unnecessary styling information from the result
- Split document: create multiple pages from a single office document (based on heading levels to split)
- Heading levels to split: choose the heading levels to split the office content on; selected heading levels and their corresponding sections will be imported in separate child pages, linked from the parent page
- Child pages naming: shown only when the target wiki page is terminal, allows to control how the "child" wiki pages, created as a result of the split operation, are named; the following naming methods are available:
- Heading names: the heading name is used as the page name; this option is the only one that makes sense when the target wiki page is not terminal, which is why the "Child pages naming" field is not shown in this case;
- Main page name and heading: the heading name is appended to the name of the target wiki page
- Main page name and numbering: an index (counter) is appended to the name of the target wiki page
- XWiki 14.10.2+, 15.0+ Terminal Child Pages: shown only for advanced users and only when the target page is not terminal, allows to control whether the "child" pages created by the split operation are terminal or not
XWiki 14.10.2+, 15.0+ The office document is imported asynchronously upon clicking on the Import button. A notification message shown at the bottom of the page is used to indicate the progress and the outcome of the import. I case of a successful import the user is redirected automatically to the target wiki page.
WYSIWYG Editor
The WYSIWYG editor provides two ways to import office content:
- Select the "Import Office file" option from the + (plus) drop down on the editor toolbar:
- You can copy paste sections from an Office file directly into the rich text area. See the CKEditor Integration documentation for more information.
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.
You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:
- Log in the wiki with a user having Administration rights
- Go to the Administration page and select the Import category
- Follow the on-screen instructions to upload the downloaded XAR
- Click on the uploaded XAR and follow the instructions
- You'll also need to install all dependent Extensions that are not already installed in your wiki
The Office Importer application comes pre-bundled with XWiki versions greater than 1.8M1, so there is no need for a manual installation. The Office Importer makes use of a running Libre Office server to convert office documents into HTML before they are finally transformed into XWiki 2.0 syntax. Thus, a Libre Office server instance is required on the server computer which hosts your XWiki installation. Beginning with XWiki 1.8.4 you can configure a Libre Office or an OpenOffice server in the following ways described below.
Configuration Tutorials
- Activating a LibreOffice server in 2 steps
- Video example of activating an OpenOffice server starting with 7.4.3 versions
Internally managed OpenOffice server process (default)
This is a very easy (and safe) option where your XWiki application takes care of managing the OpenOffice server process for you. To configure the OpenOffice server management scheme, you can use the WEB-INF/xwiki.properties configuration file:
# Settings for the OpenOffice server instance consumed by the OfficeImporter component
#-------------------------------------------------------------------------------------
#-# [Since 1.9M2]
#-# Type of the openoffice server instance used by officeimporter component.
#-# 0 - Internally managed server instance. (Default)
#-# 1 - Externally managed (local) server instance.
# openoffice.serverType = 0
#-# [Since 12.1RC1]
#-# Port numbers used for connecting to the openoffice server instance.
#-# For an internally managed server instance, it will create the process for all ports.
#-# For an externally managed server instance, only the first server port is taken into account.
# openoffice.serverPorts = 8100,8101
#-# [Since 1.9M2]
#-# If the openoffice server should be started / connected upon XE start.
#-# Default value is false
# openoffice.autoStart = false
#-# [Since 1.8RC3]
#-# Path to openoffice installation (serverType:0 only).
#-# If no path is provided, a default value will be calculated based on the operating environment.
# openoffice.homePath = /opt/openoffice.org3/
#-# [Since 1.8RC3]
#-# Path to openoffice execution profile (serverType:0 only).
#-# If no path is provided, a default value will be calculated based on the operating environment.
# openoffice.profilePath = /home/user/.openoffice.org/3
#-# [Since 1.8RC3]
#-# Maximum number of simultaneous conversion tasks to be handled by a single openoffice process (serverType:0 only).
#-# Default value is 50
# openoffice.maxTasksPerProcess = 50
#-# [Since 1.8RC3]
#-# Timeout for conversion tasks (in milliseconds) (serverType:0 only).
#-# Default value is 60 seconds
# openoffice.taskExecutionTimeout = 60000
XWiki <12.1 the property openoffice.serverPort should be used with only one value instead of openoffice.serverPorts.
XWiki <11.10.11, <12.6.3, <12.8 the default value of property openoffice.taskExecutionTimeout was 30 seconds, it has been changed to 1 min afterwards.
If your XWiki instance fails to automatically locate the install path of the OO server, here are some default install paths of the OO on different operating systems:
- Microsoft Windows XP/Vista/7:
Example for OpenOffice 3 (32-bit):
openoffice.profilePath=C:/Users/{user}/AppData/Roaming/openOffice.org/3
openoffice.homePath=C:/Program Files/OpenOffice.org 3Example for LibreOffice 3.4 (32-bit):
openoffice.profilePath=C:/Users/{user}/AppData/Roaming/LibreOffice/3
openoffice.homePath=C:/Program Files/LibreOffice 3.4Example for OpenOffice 3 (64-bit):
openoffice.profilePath=C:/Users/{user}/AppData/Roaming/openOffice.org/3
openoffice.homePath=C:/Program Files (x86)/OpenOffice.org 3Example for LibreOffice 3.4 (64-bit):
openoffice.profilePath=C:/Users/{user}/AppData/Roaming/LibreOffice/3
openoffice.homePath=C:/Program Files (x86)/LibreOffice 3.4 - Ubuntu Linux (10.04):openoffice.homePath=/usr/lib/openoffice/
- Ubuntu Linux (11.10):openoffice.homePath=/usr/lib/libreoffice/
- Fedora:
See the Guide for Fedora.
- Mac OSX:
Example for LibreOffice:
openoffice.homePath=/Applications/LibreOffice.app/Contents
If you leave your XWiki application to manage the OpenOffice server process (which is the default behaviour), your Office Importer admin UI will look something like below:
Externally managed (local) OpenOffice server process
This option allows you (the system admin) to control the OpenOffice server process as desired. This is very useful if you wish to customize OpenOffice server start-up parameters. You can configure this behaviour within the xwiki.properties file as shown below:
# Settings for the OpenOffice server instance consumed by the OfficeImporter component
#----------------------------------------------------------------------------------
#-# Type of the openoffice server instance used by officeimporter component.
#-# 0 - Internally managed server instance.
#-# 1 - Externally managed (local) server instance.
openoffice.serverType=1
#-# Port number used for connecting to the openoffice server instance.
# openoffice.serverPort=8100
#-# If the openoffice server should be started / connected upon XE start.
# openoffice.autoStart=false
Once XWiki is configured in this manner, an OpenOffice server must be manually started as a separate process. You can issue the following command to accomplish this:
Don't forget to replace <soffice> with the path to your OpenOffice executable. More information regarding OpenOffice server deployment is provided here. Also note that the Office Importer admin UI will change reflecting the new configuration as shown below:
Linux users may refer to additional installation notes here.
Auto start / Auto connect (feature)
This feature was introduced beginning with the XWiki 1.8.4 version. With this option enabled, you don't need to worry about starting / connecting the OpenOffice server from the Office Importer admin UI every time you restart XE. This option can be configured from xwiki.properties file as shown below:
openoffice.autoStart=true
Dependencies
Dependencies for this extension (org.xwiki.platform:xwiki-platform-office-ui 8.3):
- org.xwiki.platform:xwiki-platform-office-importer 8.3
- org.xwiki.commons:xwiki-commons-component-api 8.3
