For IBM® 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.
Limitations
The File Plan
Import Export Tool facilitates the migration of file plans. However,
the tool does not support the following:
- 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, and 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 ftp://ftp.software.ibm.com/software/data/cm/filenet/docs/p8doc/40x/P840_Troubleshooting.pdf.
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 - opens a dialog in which you specify
required information such as the Content Engine (CE)
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 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:
- 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," which is contained
within "Cat02" and which in turn is contained in "Cat01," type the
following command:
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
a large number of 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
except 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 sub-trees 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 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.
Attention: 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 IBM 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:
- None - When adding an entity, the tool reports
a warning in the exception log if an entity already 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 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.