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 , 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:
, , , and . 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:
, , , and . 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 . However, when using
or 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
or 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.