IBM Enterprise Records, Version 5.1.2    

Using the File Plan Import and Export tool

For IBM® Enterprise Records deployments, use the File Plan Import Export tool to import an external file plan, or export a file plan to an external environment. The tool uses an XML file to complete the import and export processes.

Overview

For details about modifying an exported XML file to include schedule inheritance, alternate retentions, disposal triggers, and dynamic holds, see the Troubleshooting File Plan Import and Export tool topic.

Limitations

Use the File Plan Import Export tool to migrate file plans. However, the tool does not support the following scenarios: First export and import custom properties, like choice lists, and classes in a separate XML file before you import the rest of the file plan. Also, after you import a file plan, entity states such as Closed or Ready for Disposition are no longer in effect.

Running the tool

You can run the File Plan Import Export tool from a command-line Java executable program. Or you can start the tool with the command file: FilePlanTool.bat or FilePlanTool.sh. You can run the tool in one of these five modes:

Configure the tool

Before you run the tool in import or export mode, you must configure the tool. To configure the tool:
  1. Go to the folder where the File Plan Import Export tool is installed.
  2. Run one of the following at the command line:
    Operating system Command
    Windows FilePlanTool -mode configure
    AIX, HP-UX, Linux, and Solaris FilePlanTool.sh -mode configure
    Enter the following information in the file plan tool dialog box:

Export a file plan

If the file plan you want to export contains any of the following items: See Export a file plan with the scope option.

After you configure the tool, you can use the tool to export a file plan. To export a file plan, type the following command:

FilePlanTool -mode export -fileplan file plan name -o XML filename.xml

Where file plan name is the name of the file plan to export and is required. If the file plan name contains spaces or special characters, place file plan name within quotations.

XML filename is the name and path of the file to create. If you do not provide a file name on the command line, the tool uses the default file name specified by the Output File Name field. This field is located in the configuration dialog box. For details about specifying the default XML output file name, see Configure the tool.

Export a file plan with the scope option

When you export a file plan, use the scope option for large file plans, or for file plans that contain custom classes or properties. To export a file plan using the scope option, type the following command:

FilePlanTool -mode export -fileplan file plan name -o XML filename.xml -scope parameter

Where file plan name is the name of the file plan to export and is required. If the file plan name contains spaces or special characters, place file plan name within quotation marks.

XML filename is the name and path of the file you want to create. If you do not provide a file name on the command line, the tool uses the default file name specified by the Output File Name field. This field is located in the configuration dialog box. When you use the tool with the scope option, the tool creates an XML file for each part the file plan. Therefore, you must specify a different XML file name each time you use the tool in export mode. For information about specifying the default XML output file name, see Configure the tool.

parameter can be any of the following items:
  • metadata: If your file plan contains custom classes or properties, this parameter is required. The metadata parameter option creates a separate XML file for custom classes and properties. Therefore, when a file plan contains custom classes or properties, the export and import processes consist of two steps each:
    • One step for the custom classes and properties
    • One step for the remainder of the file plan. If you do not use the metadata parameter, the tool exports the file plan without custom properties.
  • includecategory "record category name": Use this parameter to export a specific record category. When you use includecategory, the tool exports all the subcategories and subfolders contained within the specified record category. The record category name must include the full path in IBM Enterprise Records. For example, to export all children in the record category called Cat03, type the following command. Cat03 is contained within Cat02 which in turn is contained in Cat01.

FilePlanTool.bat -mode export -scope includecategory "/Cat01/Cat02/Cat03" -o expfile.xml

FilePlanTool.bat -mode export -scope includecategories file01.txt -o export01.xml

File01.txt contains:

/categoryB /CategoryC/SubcategoryC2 /CatogoryA/SubcategoryA1

The category name is represented by the full path name and one record category per line.

Import/Update a file plan

To import a file plan or a segment of a file plan, run the tool in import mode. Specify the XML file that the tool created in export mode. If your file plan contains custom classes or properties, the import process requires two steps. The first step imports the custom classes and properties in the file plan. The second step imports the remainder of the file plan. Import the custom classes and properties first. Then wait at least 5 minutes before importing the file plan because the custom class and property metadata is cached in memory. The cache time-to-live (TTL) is 5 minutes, after which the cache is cleared. To import/update a file plan, type the following command:

FilePlanTool -mode import -f XML filename.xml -reimportoption option

FilePlanTool -mode update -f XML filename.xml -reimportoption option

XML filename is the name and path of the file you want to import. The tool uses the default file name specified by the Output File Name field in the configuration dialog if you do not provide a file name. For information about specifying the default XML output file name, see Configure the tool.

The reimport option determines the default behavior of the tool when importing an entity that exists in a file plan. For details about the reimport option, see Use the reimport option.

In Import mode, the tool does not use the scope option, but looks at an XML tag to determine what to import. You must provide a different XML file name for metadata (custom classes and properties) and the file plan.

Attention: The ClassificationScheme tag in the XML file specifies the name of the file plan.

Run the tool in Update mode to make minor modifications after the initial import of a file plan. Distinguish subsequent updates from the initially imported XML files. Specify update as the InputMode attribute of the FilePlan tag in the XML file. You cannot modify a custom property (such as a choice list) by using the Update mode.

See the Troubleshooting and Support node in the information center or theIBM FileNet P8 Troubleshooting Guide in the Product Documentation for FileNet® P8 Platform page if you receive an error message, or the import process stops. In most cases, the import process stops after encountering an error, and does not display any message.

If necessary, run Hold Sweep to apply conditional holds on entities after the import because the tool does not import conditional holds. See Limitations.

Validate a file plan

After you manually create an XML file, verify that the XML file does not contain any errors or non-compliance issues. You can validate the file through the File Plan Import Export tool. To run the Import Export tool in validate mode, type the following command:

FilePlanTool -mode validate -f XML filename.xml

XML filename is the name and path of the file you want to validate. The tool uses the default file name specified by the Output File Name field in the configuration dialog if you do not provide a file name. For information about specifying the default XML output file name, see Configure the tool.

Use the reimport option

Use the reimport option to determine the default behavior of the tool when importing an entity that exists in a file plan. The reimport option has three parameters: Use the Skip option after a failed import of a large file plan. During the second attempt at importing the same file plan, the Skip option avoids reimporting entities that are successfully imported. However, if the second attempt at importing requires minor modifications to entities that are successfully imported the first time, use the Replace option. During subsequent imports of minor modifications to a few entities, specify Action="Modify" (in the RMEntityObjectType section of the XML file) for the entities. Change these entities instead of changing the original XML file. Also, use the Update mode to more easily identify subsequent updates from initial full imports. See Import/Update a file plan.


Feedback

Last updated: November 2013
fileplan_import_export.htm

© Copyright IBM Corporation 2013