Import/Export Tools
===================

Import/export support is provided via plugins. These plugins can be accessed
over the web via the Journal Manager's "Import/Export Data" page, or via the
command line using the tools/importExport.php utility.

OJS 2.0.1 ships with two of these plugins: the "Articles & Issues XML Plugin",
which allows import and export of articles and issues, and the "Users XML
Plugin", which allows import and export of users.

Additional plugins may be installed simply by copying them into subdirectories
of the plugins/importexport directory; they will automatically be added to the
list of available plugins.

Each import/export plugin has a unique name, defined in its PHP source code, by
which it can be invoked using the command line tool. To get a list of all
plugins via the command line, execute the following:

	php tools/importExport.php list

To invoke a particular plugin from the command line, execute the following:

	php tools/importExport.php [pluginName] [arguments ...]

For example, to get help from the NativeImportExportPlugin on its usage:

	php tools/importExport.php NativeImportExportPlugin usage

Each plugin requires a different set of arguments; for information on each,
refer to its documentation. The two plugins that ship with OJS 2.0.1 are
described below.

Developers of new plugins are encouraged to follow the standards set in the two
included plugins. For example:

	- Command-line argument styles should be consistent;
	- Journals should be addressed by path;
	- Local hrefs, such as <href src="localFile"/>, should be supported
	  only by the command line tool and should be discarded by the web-
	  based tool for security reasons;
	- XML-based import/export plugins should use the XMLReader and XMLWriter
	  classes to ensure compatibility with PHP4 and PHP5;
	- etc.


Articles & Issues XML Plugin
============================

This plugin supports import and export of articles and issues in an XML format
based on the DTD supplied in plugins/importexport/native/native.dtd. It supports
the following root elements: <article>, <articles>, <issue>, and <issues>.

The plugin is intended to provide an easy way to import back-issues into OJS,
often by converting data from another format (e.g. another dialect of XML or a
database). Only presentation-level data is supported, i.e. while it is possible
to import and export issue information, articles and article metadata, etc., it
is not possible to capture editorial data such as peer reviews, copyediting
comments, etc.

There are two equivalent methods that can be used to access the plugin:
1. via the Journal Manager's "Import/Export Data" interface
2. via the tools/importExport.php command-line tool

To get usage information for the command line tool, execute the following:

php tools/importExport.php NativeImportExportPlugin usage

The plugin can be used to move articles and issues from one OJS installation to
another, but note that this does NOT include the editorial history of the
documents. For example, if an article is peer-reviewed, the peer reviews will
not be part of the export document and will not be imported into the target
installation of OJS.

Importing Data
--------------
Before importing data, ensure that the XML file validates against the DTD.
Many XML editors and tools such as xmllint are capable of validating XML files
against a DTD.

The import XML will either link to (using the href tag) or encapsulate (using
the embed tag) files such as PDF articles and cover images. Using the embed tag
allows the file contents to be embedded directly in the XML document using
base64. Using the href tag allows the XML to refer to external files, either on
the server filesystem or at an external URL. Note that referring to local files
is disabled for security reasons when using the web-based import/export tool.

Several root elements are supported for import documents: <article>,
<articles>, <issue>, and <issues>. The import process will differ depending on
which root element is chosen. For example, the import tool will need to know
which journal will receive the new issue when an import document begins with
<issue>. However, when using <article> or <articles> as the root node, the
import tool will need to know which journal, issue and section will receive the
new articles. The web-based import tool will prompt for this context as needed;
it will need to be specified manually when using the command-line tool.

To import a document with the command-line tool, use the following syntax
(wrapped for clarity):

php tools/importExport.php NativeImportExportPlugin import
	[xmlFileName] [journal_path] [user_name] ...

...where:
	[xmlFileName] is replaced by the filename of the XML document to import
	[journal_path] is the path of the journal to receive the import
		document, as defined on the Site Administrator's "Hosted
		Journals" interface. The path also appears in URLs to the
		journal, i.e. in http://www.myjournal.com/index.php/demo/user,
		"demo" is the journal path.
	[user_name] is the username of the account that will receive control
		of the imported documents. (Note that this does not mean that
		authorship will be attributed to this account in the published
		journal; however, the articles will appear in this user's
		archive.)

If <article> or <articles> root nodes are used, additional parameters will be
required to specify the section and issue. See the tool usage text for details.

Exporting Data
--------------
Data can be exported either using the web interface or the command-line tool.
To export data using the command-line tool, use one of the following methods
(wrapped for clarity):

php tools/importExport.php NativeImportExportPlugin export [xmlFileName]
	[journal_path] articles [articleId1] [articleId2] ...

php tools/importExport.php NativeImportExportPlugin export [xmlFileName]
	[journal_path] article [articleId]

php tools/importExport.php NativeImportExportPlugin export [xmlFileName]
	[journal_path] issues [issueId1] [issueId2] ...

php tools/importExport.php NativeImportExportPlugin export [xmlFileName]
	[journal_path] issue [issueId]

...where:
	[xmlFileName] is replaced by the filename of the XML document to export
	[journal_path] is the path of the journal from which to export data,
		as defined on the Site Administrator's "Hosted Journals"
		interface. The path also appears in URLs to the journal, i.e.
		in http://www.myjournal.com/index.php/demo/user, "demo" is the
		journal path.

Each of these methods will export a document with a different root node: first
for multiple articles, then a single article, then multiple issues, then a
single issue. For each, one or multiple IDs need to be specified.

Article IDs can be found in the editorial interface for many roles, e.g on a
submission's Summary, Review, or Editing pages.

Issue IDs can be found in the Editor's "Future Issues" or "Back Issues"
interface. Select the issue you wish to export and examine the URL. It will
resemble the following:
	http://www.myjournal.com/index.php/demo/editor/issueToc/12

In this example, the issue ID is 12.

Example
-------
To export issue ID 3 from the journal having path "demo" to
the file "out.xml" (note that issue IDs can be database IDs or public IDs, with
public IDs taking precedence):

php tools/importExport.php NativeImportExportPlugin export out.xml demo issue 3


Users XML Plugin
================

This plugin supports import and export of users and their roles based on the
DTD supplied in plugins/importexport/users/users.dtd, with "users" as the root
element.

To get usage information for the command line tool, execute the following:

php tools/importExport.php UserImportExportPlugin usage

For example, to export all users and their roles from the journal with path
"demo", execute the following:

php tools/importExport.php UserImportExportPlugin export out.xml demo

This plugin treats emails as unique user identifiers in order to ensure that
duplicate users are not created. If an existing user is found in the database
with the same email as an imported user, no additional user is created; the
roles described in the XML file are attributed instead to the existing user.
Usernames are treated likewise.
