Use the File Plan Import and Export Tool

Overview

For IBM InfoSphere Enterprise Records deployments, you can 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. For details about the XML schema and its elements, see File Plan XML Schema.

For details about modifying an exported XML file to include schedule inheritance, alternate retentions, disposal triggers, and dynamic holds (conditional holds), refer to the File Plan Import and Export Tool section found at Product Documentation for FileNet P8 Platform.

Limitations

The File Plan Import Export Tool facilitates the migration of file plans. However, the tool does not support the following:

In addition, you must first export and import custom properties (such as 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, or you can start the tool with the command file, FilePlanTool.bat or FilePlanTool.sh.

You can execute 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. Navigate to the folder where the File Plan Import Export Tool is installed.
  2. Execute one of the following at the command line:

    In Windows:
    FilePlanTool -mode configure

    In UNIX:
    ./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 quotes.

XML filename is the name and path of the file to create. If you do not provide a filename on the command line, the tool uses the default file name specified by the Output File Name field in the tool's configuration dialog box. For details about specifying the default XML output filename, 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 quotes.

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 in the tool's 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 filename each time you use the tool in export mode. For information about specifying the default XML output filename, see Configure the tool.

parameter can be any of the following:

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 thereof, execute the tool in import mode and 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. One step imports the custom classes and properties in the file plan, and the second step imports the remainder of the file plan. Import the custom classes and properties first, then wait at least five minutes before importing the file plan because the custom class and property metadata is cached in memory. The cache time-to-live (TTL) is five 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. If you do not provide a file name on the command line, the tool will use the default file name specified by the Output File Name field in the tool's configuration dialog. For information about specifying the default XML output filename, see Configure the tool.

The reimport option determines the default behavior of the tool when importing an entity that already 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 filename for metadata (custom classes and properties) and the file plan.

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

You can run the tool in Update mode to make minor modifications after the initial import of a file plan, and you can 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 FileNet P8 Troubleshooting Guide 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 by validating it 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. If you do not provide a file name on the command line, the tool will use the default file name specified by the Output File Name field in the tool's configuration dialog. For information about specifying the default XML output filename, 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 already 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 have been successfully imported. However, if the second attempt at importing requires minor modifications to entities that have been successfully imported the first time, use the Replace option.

During subsequent imports of minor modifications to a small number of entities, specify Action="Modify" (in the RMEntityObjectType section of the XML file) for the entities, instead of making changes to 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.