Exporting and importing collection configurations

You can export a collection from one system, and then import the collection into a different system. However, you can export and import collections only between systems that are running the same version of the product.

If you export a collection, you can import it only to a system that uses the same operating system. For example, you cannot export a collection from a system that is installed on Linux and import it to a system that is installed on Windows.

Exporting collections

To export a collection, you use the esadmin export command to export one collection at a time. There is no support for exporting collections in the administration console.

1. Log in as the default IBM® Content Analytics with Enterprise Search administrator. In a multiple server configuration, you must log in on the controller server. The command fails if you attempt to run it from any other server.
2. Enter the following commands:

   esadmin export -help esadmin export -cid collection_id [-fname export_filename.zip] [-verbose]

   Where:

   -help

   Provides help information for the command.

   -cid collection_id

   Specifies the collection ID for the collection to be exported.

   Tip: To determine the collection ID for the collection that you want to export, click Actions > View collection settings in the administration console or use the esadmin report collections command.

   -fname export_filename

   Specifies the path to the export file. If the file name is not absolute, then the ES_NODE_ROOT/dump directory is assumed. If you omit this option, a file that uses the following naming convention is created in the ES_NODE_ROOT/dump directory:

   _export_yyyyMMdd_HHmmssz.zip

   where:

   yyyyMMdd

   Is the current year, month, and day when the export command is run.

   HHmmss

   Is the current hour, minute, and second when the export command is run.

   z

   Is the time zone offset from GMT when the export command is run. For example, Pacific Standard Time is GMT -0800.

   -verbose

   Displays information that can help troubleshoot the export operation.

Importing collections

To import a collection, you use the esadmin import command to import one collection at a time. There is no support for importing collections in the administration console.

1. Log in as the default IBM Content Analytics with Enterprise Search administrator. In a multiple server configuration, you must log in on the controller server. The command fails if you attempt to run it from any other server.
2. Enter the following commands:

   esadmin import -help
   esadmin import -fname export_filename
        [-cid new_collection_id]
        [-name new_collection_name]
        [-colDataDir new_collection_data_directory]
        [-force]
        [-verbose]

   Where:

   -help

   Provides help information for the command.

   -fname export_filename

   Specifies the path to the file that you want to import. This is the file that was created when you ran the esadmin export command to export collection configurations. If the file name is not absolute, then the ES_NODE_ROOT/dump directory is assumed.

   -cid new_collection_id

   Specifies a new collection ID if the collection needs to be imported with a different ID. If you specify the same collection ID when you import a collection, most of the session IDs are not changed. The session ID is based on the collection ID, such as collectionID.indexer. However, the session IDs of crawlers and crawler plug-ins might change. In addition, data listener authentication and authorization data might not be preserved when you import a collection.

   Tip: To determine the collection ID for the collection that you want to import, click Actions > View collection settings in the administration console or use the esadmin report collections command.

   -name new_collection_name

   Specifies a display name for the collection. If you do not specify a display name when you import the collection, the default value, Collectioncollection_ID, is used

   -colDataDir new_collection_data_directory

   Specifies the data directory for the collection. If omitted, a default directory is assigned.

   -force

   Forces the import of a collection that already exists in the target system. The system uses the collection ID for the imported collection to determine which collection to replace in the target system.

   Important:

   • After you import a collection, you cannot import a collection with the same collection ID again unless you use this option to force the collection to be imported.
   • A collection that is imported by force does not retain the text analysis engines, dictionaries, and crawler plug-ins. These are overwritten with the information contained in the imported collection.
   • Any crawlers associated with the collection are removed and replaced with crawlers that are specified in the import file. Because the crawlers are removed, all crawler metadata and documents that are not yet parsed are also removed. After the collection is imported, you must recrawl all documents to regenerate this data for the imported crawlers.

   -verbose

   Displays information that can help troubleshoot the import operation.

Usage guidelines

Text analysis engines and dictionaries

Any text analysis engines and dictionaries (such a synonym, stop word, and boost word dictionaries) that are associated with a collection in the export system are not exported with the collection configuration data. Only the name associations to text analysis engines and dictionaries are exported.

On import, if a text analysis engine or dictionary with the same name exists in the target system, then it is associated with the imported collection. Otherwise, a warning message is displayed to indicate that the associations could not be established. For this reason, you should upload the text analysis engines and dictionaries to the target system and use the same names that were used in the imported collection.

If a text analysis engine or dictionary with the same name does not exist in the target system, then the association is broken. If the association is broken, the collection will function properly in the target system, but the collection will not use the corresponding text analysis engines or dictionaries.

Crawlers

You must ensure that the crawler prerequisites are installed and configured in the target system.

Imported crawlers do not work unless the data sources that the crawlers crawl are accessible. For example, if the collection includes a file system crawler that crawls a local file system, the crawler cannot crawl unless the same directory structure exists in the target system.

Crawler plug-ins are not exported. When you import a collection, a warning message is displayed, and then the import continues to completion. After you import the collection, update the crawler properties and associate the crawler plug-ins. You must ensure that the crawler plug-ins are deployed on the target system to ensure the proper functioning of the crawler.

Restarting the system

If you specify the same collection ID when you import a collection and do not specify the colDataDir option, or if you specify the colDataDir option with a different data directory from the one that was used in the original system, you must restart the new system before you start any crawlers in the imported collection.

Running the esadmin stop and esadmin start commands on the new system ensures that the changed value for the collection's data directory is correctly reflected.

If you specify the same collection ID when you import a collection, and you specify the same data directory in the colDataDir option, you do not need to restart the system.