Plugins/ZoteroImport

With this plugin you can move your Zotero research into Omeka, making it possible to further organize and exhibit your Zotero library. Just sync your library to the Zotero server, tell the Zotero Import plugin what library you want to import, and it'll pull in source items, notes, files, and web snapshots.

Requirements

Sync Zotero library: The Zotero library must be synced to the Zotero sync server prior to import. To import files, the Zotero client must be set to sync attachment files. You can find instructions on how to do this at the Zotero website.

Atom Feed URL: Every Zotero library and collection has an Atom feed URL. You can find this URL on the library or collection page of the Zotero website, under "Subscribe to this feed." Unpublished libraries do not have a feed URL readily accessible, but you can construct it using the following URLs as templates:

The user or group owner can get you the userID, groupID, and collectionID.

Private key: To access access private libraries and collections and to download attachments (files and web snapshots), a private key is required. A key is not necessary to access citations saved in public libraries and collections. The owner of the library can generate private keys in their account settings. Private keys must be set to allow third party access.

PHP Zip extension: Zotero stores web snapshots in ZIP files containing files with Base64 encoded filenames. The import plugin attempts to decode the filenames using PHP's Zip extension. If your server does not have this extension installed, the plugin does not decode the filenames. The import will still save web snapshots, but the filenames will be obfuscated, making access near-worthless.

Installation and Importing

1. If you want to import all file types, you must disable file upload validation in Omeka Admin > Settings > Security Settings before import.

2. Once you've installed the plugin, go to the "Zotero Import" tab in the admin interface and fill out the form (/admin/zotero-import).

3. To fill out the form, you will need find the feed URL to the Zotero library you want to import and, if desired or necessary, a private key to access those sources. Click "Continue" to begin the importing process.

4. Depending on the size of the library, the import process may take some time to complete. Because of this we suggest that you log background processes:

  • In omeka/application/config/config.ini make sure log.processes = true
  • In omeka/application/logs/ make sure a processes.log file exists and is writable

This is not required but will be helpful if something goes wrong halfway through a long import. It's important to note that the import process is only as stable as the Zotero API. If you encounter errors, delete the import and try again.

Stopping and Deleting an Import

If you make a mistake, you may stop an import at any time by clicking "Stop Import" in the Zotero Import admin panel. You may also delete the items from an import after the process finishes, by clicking "Delete Import." Deleting imports will delete all imported items and files.

Features

The plugin imports Zotero libraries and collections, including source items, notes, files, and web snapshots. Web snapshots are zipped up directories containing the files needed to render the web snapshot.

To minimize data loss that often occurs when migrating between systems, the plugin adds a new Zotero element set containing elements identical to the fields used by Zotero. In addition to mapping data to the Zotero element set, the plugin maps data to the native Dublin Core element set to maximize interoperability and ease integration with Omeka. The Zotero element set is large, but the plugin provides a helper function to build strings from the elements therein (see the zotero_import_build_zotero_output() function below).

The plugin also adds a field to the advanced search page that narrows search results by Zotero item type. Every Zotero item has an item type, so it's a helpful way to sort through your items.

Using Zotero Data in Omeka

  • Return custom text built from elements from the Zotero element set:
/**
 * Returns custom text built from elements from the Zotero element set.
 * 
 * @param array $parts The parts of the output text mapped from Zotero elements.
 * array(
 *     array(
 *         'element'   => {Zotero element name, text, required}, 
 *         'prefix'    => {part prefix, text, optional}, 
 *         'suffix'    => {part suffix, text, optional}, 
 *         'all'       => {get all element texts?, boolean, optional}, 
 *         'delimiter' => {element text delimiter, text, optional}
 *     ), 
 *     array([...])
 * )
 * @return string The output text.
 */
zotero_import_build_zotero_output($parts = array());
  • Return all items of a particular Zotero item type:
/**
 * Returns items of a particular Zotero item type. Uses the Item Type element in 
 * the Zotero element set.
 *
 * @param string Search items with this Zotero item type.
 * @param int|null Search only in this collection.
 * @param int Maximum number of items to return.
 * @return array An array containing item results.
 */
zotero_import_get_items_by_zotero_item_type($typeName, 
                                            $collectionId = null, 
                                            $itemLimit = 10);
  • Return all items of a particular Zotero user or group:
get_items(array('collection' => $collectionId), $itemLimit = 10)
  • Return all notes of a particular item:
item('Zotero', 'Note', $options = array(), $item = null);
  • Return all attachments of a particular item:
loop_files_for_item($item = null);