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:
- Cross data model export/import. For example, if you export from
a PRO data model object store, you cannot import into a DoD data model
object store.
- Exporting or importing record objects, volumes, document objects,
security information, and security markings.
- Rollback mechanism.
- Exporting properties with a null value. For example, exporting
a phase of a disposition schedule with no retention period. Also,
importing the disposition schedule into another object store, does
not update the retention period to null. However, you can manually
update the XML file to update the retention period. For more information,
see the Troubleshooting File Plan Import and Export tool topic.
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: opens a dialog in which you specify
required information. This required information is the Content Platform Engine server name, object
store name, administrator user name and password, and mode (import
or export).
- Export: creates a fully compatible and compliant
XML file that you can later import into another environment.
- Import/update: imports a specified XML file
into an environment.
- Validate: reads an XML file to verify compatibility
and compliance.
Export a file plan
If the file plan you want
to export contains any of the following items:
- Custom classes or properties
- More than 300,000 folders
- A record category that includes more than 15,000 folders
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
- includecategories file 01: Use this parameter to export only the record categories and their
children specified in the input text file file 01. Use the includecategories parameter to export
many record categories to the same file without specifying each record
category name in the command line. To use this parameter, type the
following command:
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.
- excludecategory "excluded
record category name": Use this parameter to exclude
a specific record category and its children. For example, if excluded record category name is "Cat01/Cat02/Catlarge,"
the tool exports all the record categories and record folders in the
file plan with an exception. The exception is the record categories
and record folders contained within the node "Cat01/Cat02/CatLarge". This parameter operates similarly to includecategory.
- excludecategories file 02: Use this parameter to exclude the subtrees of root names specified
in the file 02 text file. This parameter operates
similarly to includecategories.
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:
- None: When adding an entity, the tool reports
a warning in the exception log if an entity exists, does not add the
entity, and continues.
- Skip: When adding an entity, the tool skips
over any existing entities, continues, and reports the skip action
in the activity log.
- Replace: When adding an entity, the tool
replaces any existing entities, continues, and reports the modify
action in the activity log.
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.