The export and import tools allow to copy (synchronize, replicate) documents between Daisy repositories that have different namespaces.

It is required that the repositories have different namespaces in order to keep the identity of the documents. For one-time transfer of documents from one repository to another, a tool could be made which recreates the documents in the target repository without preserving their IDs, which would then also require adjusting links in the content of documents. However, the import/export tools documented here do not cover this use-case.

An export not only contains documents but also schema, variant and namespace information.

The export tool can export all documents or subsets of documents (expressed using queries or a manual enumeration). Both upon export and import, manipulation of the content is possible. There are some built-in possibilities, e.g. to drop fields and parts from a document upon export or import, and for ultimate flexibility you can implement custom logic in a Java class. The import tool is smart enough to not update documents if there are no changes, so that no unncessary update events are caused.

The export and import tools are command-line applications, though the code is designed such that adding other user interfaces, or integration in for example the Daisy Wiki, should be possible.

Note that version history or time/user of the last modification is not exported/imported, the import tool simply uses the normal Daisy APIs to create/update content in the target repository. As such, the export/import tools are not a replacement for backup.

Applications

Export/import can be used for various purposes:

• Distributing a set of documents (for example, product documentation) to the Daisy repositories of clients, who can meanwhile also create their own content in Daisy that links to your documents. You can deliver a fresh export to them from time to time.
• Replicating content from an internal Daisy to an externally-visible Daisy. The export/import here serves as more controlled way to put documents live, and can also be used to decouple the load on the external Daisy from the internal one. In addition, you can export to multiple Daisy servers for load-balancing.
• Initializing a repository with some initial content. This is useful when doing Daisy-based projects, where you may want to upload some default data (navigation trees, home pages and other special pages). In this scenario, you will typically create the export data 'manually'.

Basic usage scenario

Creating an export

To define the documents to export, we need to create a file, lets call it exportset.xml, with the following content:

<?xml version="1.0"?>
<documents>
 <query>select id where true</query>
</documents>

Go to <DAISY_HOME>/bin (or put this directory in the PATH variable)

Execute

daisy-export -u <username> -p <password> -f /path/to/exportset.xml -e /path/to/exportlocation[.zip]

The /path/to/exportlocation should be:

• a non-existing file ending on ".zip"
• a non-existing or empty directory

If not specified, the daisy-export tool will by default connect to a Daisy repository server on localhost listening on the default port (9263). To connect to another repository server, use the -l (lowercase L) option:

daisy-export -l http://hostname:9263 ....

Instead of specifying the password using -p, you can also leave out the -p option and you will be prompted for the password interactively.

If something goes wrong, the following message will be printed:

*** An error occured ***

followed by a description of the error and a filename to which the complete stack trace of the error has been written (if it could not be written to a file, it will be printed on screen).

If everything succeeds, a summary of the number of exported documents will be printed, as well a file will be generated with a detailed listing of these documents.

Export or import can be safely interrupted by pressing Ctrl+C. If you do this in the middle of an import or export, the summary file that lists the documents processed so far will still be created.

Importing the export

To import the just created export, execute

daisy-import -u <username> -p <password> -r Administrator -i /path/to/exportlocation[.zip]

The -r argument specifies that the Administrator role should be made active when logging in to the repository. The Administrator role is required to create certain administrative entities such as namespaces, branches, languages, and schema types. If these would already exist, a non-Administrator role can be used as well.

Again, specify -l (repository server URL) if necessary.

If everything succeeds, a summary of the number of imported documents (and failures) will be printed, and a file will be generated with a detailed listing of the imported and failed documents.