File plan import and export troubleshooting and tips

This topic includes information about the common causes of errors that you might encounter when using the File Plan Import Export Tool. Also, this topic discusses how to reduce the likelihood of encountering errors.

Common causes of errors

When you import a file plan, you might encounter an error. In most cases, the import process stops after encountering an error, and does not display any message. The cause of the error may be any of the following:

The File Plan Import Export Tool includes options that you can use to address potential errors. These options are discussed in the sections that follow.

Manually creating an XML file

For the purposes of discussion, manually creating an XML file refers to creating an XML file by means other than the File Plan Import Export Tool (for example, using macros or other programmatic means to create an XML file). Before you can import a file plan, you must create an XML file that is both compliant with the XML standard and compatible with FileNet software's XML schema.

If you manually create an XML file to use in importing a file plan, you must base the file on the XML schema provided by IBM. Details about the XML schema are provided in the File Plan XML Schema help topic in the Developer Roadmap.

NOTE  Most of the errors that occur while importing a file plan are caused by incompatible or non-compliant XML files. Therefore, extra care should be taken if you manually create an XML file.

After you manually create an XML file, we highly recommend that you run the File Plan Import Export Tool in validate mode. The tool in validate mode reads an XML file and verifies that the file does not contain any errors or non-compliance issues. (See Validating a file plan for details about the validate mode.)

Some of the options that are available when you manually create an XML file are included in the sections Subcategory schedule inheritance and ConditionXML Property.

Observing the File Plan Import Export Tool functionality

If you intend on manually creating an XML file to import a large file plan with custom classes and objects, we recommend that you first create a small file plan and related metadata, and execute the tool in export mode. Such an exercise is particularly useful before you manually create an XML file for file plans with conditional holds, internal event triggers, and alternate retention objects, all of which contain the complex conditionXML property. Even though you create a file with the correct XML format, the XML file may have incorrect property values or syntax, which may cause an error during importation. Exporting a small file plan enables you to review the XML file that the tool created, and to observe the syntax and property values in the XML file.

Using the scope metadata option

If your file plan contains custom classes or properties, you must use the scope metadata option during the export process. The scope metadata 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, and the other for the remainder of the file plan. The File Plan Import and Export Tool help topic includes procedures for using the scope metadata option.

Using the reimport option

The reimport option is used to specify the behavior of the add action in the XML file. The reimport option has three parameters:

During the initial importation of a large file plan, you may want to use the Skip option. In case of failure and during the second attempt at importing the same file plan, use the Skip option to avoid re-importing 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, you may want to use the Replace option.

During subsequent importations of minor modifications to a small number of entities, we recommend that you specify Action="Modify" in the XML file for the entities, instead of making changes to the original XML file. Also, using the Update mode allows you to more easily identify subsequent updates from initial full imports.

Subcategory schedule inheritance

When you create a subcategory, you can use the Record Manager UI to specify that the subcategory inherits the parent disposition schedule. If you manually create the XML file to import the file plan in which the subcategory is contained, you have an option to specify that the subcategory does not inherit the parent’s schedule and provide a different schedule.

In the XML file you create, use the DisposalScheduleInheritedFrom property to indicate whether the record category inherits the disposal schedule from the parent. For example:

<RecordCategory Name="myCat2" Level="2" ParentPath="/myCat1">
    <Properties>
        <Property Name="AGGREGATION" Value="RecordCategory" />
        <Property Name="IsPermanentRecord" Value="false" />
        <Property Name="IsVitalRecord" Value="false" />
        <Property Name="CurrentPhaseExportFormat"></Property>
        <Property Name="IsDeleted" Value="false" />
        <Property Name="HomeLocation"></Property>
        <Property Name="VitalRecordReviewAction"></Property>
        <Property Name="IncrementedBy" Value="1" />
        <Property Name="RecordCategoryName" Value="myCat2" />
        <Property Name="DisposalScheduleInheritedFrom" Value="/myCat1" />
        <Property Name="Reviewer" Value="ylin" />
        <Property Name="RecordCategoryIdentifier" Value="myCat2" />
        <Property Name="VitalRecordDisposalTrigger"></Property>
        <Property Name="Inactive" Value="false" />
        <Property Name="Location"></Property>
        <Property Name="DateOpened" Value="2006-03-07T14:16:00-08:00" />
        <Property Name="DisposalSchedule">
                <ObjectRef ClassId="DisposalSchedule" ObjectId="myDispSchedule" />
        </Property>
    </Properties>
</RecordCategory>

There are four scenarios under which you can use the DisposalScheduleInheritedFrom property, as follows:

<Property Name="DisposalScheduleInheritedFrom" Value="/myCat1" />

ConditionXML property

When you manually create an XML file to import a file plan, you have the option of specifying values for the ConditionXML property, which the file plan import tool uses to import the following:

For Alternate Retentions, Internal Event Triggers and Dynamic (conditional) Holds entities, the ConditionXML property stores search conditions in XML format. The properties tag in ConditionXML stores the property name/value/operator for the IBM InfoSphere Enterprise Records user interface. The sql tag in ConditionXML stores the SQL statement. When you enter the property value of ConditionXML for file plan import, the special characters (< > & " ') need to be converted to the standard representation (&lt; &gt; &amp; &quot; &apos;).

Below are sample XMLs of entities containing ConditionXML property for File Plan Import Export.

Sample of ConditionXML for Alternate Retention

<Phases>
  <RMEntity Type="Phase" Name="myPhase1">
    <Properties>
      <Property Name="PhaseAction"></Property>
      <Property Name="RetentionPeriodDays" Value="0" />
      <Property Name="RetentionPeriodYears" Value="10" />
      <Property Name="RMEntityDescription" Value="my phase 1" />
      <Property Name="RetentionPeriodMonths" Value="0" />
      <Property Name="PhaseNumber" Value="1" />
      <Property Name="ExportFormat"></Property>
      <Property Name="IsScreeningRequired" Value="true" />
      <Property Name="DisposalSchedulePtr">
        <ObjectRef ClassId="DisposalSchedule" ObjectId="myDispSchedule" />
      </Property>
      <Property Name="PhaseName" Value="myPhase1" />
      <Property Name="AlternateRetentions">
        <ObjectValue Type="AlternateRetention">
          <Properties>
            <Property Name="RetentionBase" Value="CutoffDate" />
            <Property Name="ConditionXML" Value="&lt;response xmlns=&quot;http://filenet.com/namespaces/wcm/apps/1.0&quot;&gt;&lt;objectset&gt;&lt;count&gt;1&lt;/count&gt;&lt;customobject&gt;&lt;properties&gt;&lt;property&gt;&lt;symname&gt;ClosedBy&lt;/symname&gt;&lt;operator&gt;IS EQUAL&lt;/operator&gt;&lt;value&gt;Administrator&lt;/value&gt;&lt;/property&gt;&lt;/properties&gt;&lt;aggregation&gt;&lt;/aggregation&gt;&lt;sql&gt; AND ([ClosedBy] = &apos;Administrator&apos;)&lt;/sql&gt; &lt;/customobject&gt;&lt;/objectset&gt;&lt;/response&gt;" />
            <Property Name="RetentionPeriodMonths" Value="0" />
            <Property Name="RetentionPeriodYears" Value="5" />
            <Property Name="RetentionPeriodDays" Value="0" />
          </Properties>
        </ObjectValue>
        <ObjectValue Type="AlternateRetention">
          <Properties>
            <Property Name="RetentionBase" Value="DateClosed" />
            <Property Name="ConditionXML" Value="&lt;response xmlns=&quot;http://filenet.com/namespaces/wcm/apps/1.0&quot;&gt;&lt;objectset&gt;&lt;count&gt;1&lt;/count&gt;&lt;customobject&gt;&lt;properties&gt;&lt;property&gt;&lt;symname&gt;RMEntityDescription&lt;/symname&gt;&lt;operator&gt;LIKE&lt;/operator&gt;&lt;value&gt;something&lt;/value&gt;&lt;/property&gt;&lt;/properties&gt;&lt;aggregation&gt;&lt;/aggregation&gt;&lt;sql&gt; AND ([RMEntityDescription] LIKE &apos;%something%&apos;)&lt;/sql&gt; &lt;/customobject&gt;&lt;/objectset&gt;&lt;/response&gt;" />
            <Property Name="RetentionPeriodMonths" Value="0" />
            <Property Name="RetentionPeriodYears" Value="5" />
            <Property Name="RetentionPeriodDays" Value="0" />
          </Properties>
        </ObjectValue>
      </Property>
    </Properties>
  </RMEntity>
</Phases>


Sample of Disposal Trigger with ConditionXML:

<DisposalTriggers>
    <RMEntity Type="DisposalTrigger" Name="Date Created">
       <Properties>
           <Property Name="DisposalTriggerName" Value="Date Created" />
           <Property Name="EventType" Value="3" />
           <Property Name="CycleYears" Value="0" />
           <Property Name="CycleDays" Value="0" />
           <Property Name="AGGREGATION" Value="RecordInfo" />
           <Property Name="ConditionXML" Value="&lt;response xmlns=&quot;http://filenet.com/namespaces/wcm/apps/1.0&quot;&gt;&lt;objectset&gt;&lt;count&gt;1&lt;/count&gt;&lt;customobject&gt;&lt;properties&gt;&lt;property&gt;&lt;symname&gt;DateCreated&lt;/symname&gt;&lt;displayname&gt;Date Created&lt;/displayname&gt;&lt;propertytype&gt;3&lt;/propertytype&gt;&lt;value/&gt;&lt;operator&gt;IS NOT NULL&lt;/operator&gt;&lt;jointype&gt;AND&lt;/jointype&gt;&lt;/property&gt;&lt;/properties&gt;&lt;aggregation&gt;RecordInfo&lt;/aggregation&gt;&lt;sql&gt; SELECT OIID , ID , RMENTITYTYPE FROM RecordInfo WHERE ( DateCreated IS NOT NULL )&lt;/sql&gt;&lt;/customobject&gt;&lt;/objectset&gt;&lt;/response&gt;" />
           <Property Name="CycleMonths" Value="0" />
       </Properties>
    </RMEntity>
</DisposalTriggers>

Sample of Dynamic Hold with ConditionXML:

<Holds>
    <RMEntity Type="RecordHold" Name="dynamic Hold">
       <Properties>
           <Property Name="Active" Value="true" />
           <Property Name="HoldName" Value="dynamic Hold" />
           <Property Name="HoldReason" Value="dynamic Hold" />
           <Property Name="ConditionXML" Value="&lt;response xmlns=&quot;http://filenet.com/namespaces/wcm/apps/1.0&quot;&gt;&lt;objectset&gt;&lt;count&gt;2&lt;/count&gt;&lt;customobject&gt;&lt;properties&gt;&lt;property&gt;&lt;symname&gt;RecordCategoryName&lt;/symname&gt;&lt;displayname&gt;Record Category Name&lt;/displayname&gt;&lt;propertytype&gt;8&lt;/propertytype&gt;&lt;selectable&gt;true&lt;/selectable&gt;&lt;value&gt;dynamic&lt;/value&gt;&lt;operator&gt;like&lt;/operator&gt;&lt;jointype&gt;AND&lt;/jointype&gt;&lt;/property&gt;&lt;/properties&gt;&lt;aggregation&gt;RecordCategory&lt;/aggregation&gt;&lt;sql&gt; SELECT ro.[RecordCategoryName] , ro.[RecordCategoryName] FROM RecordCategory ro Where ro.[RecordCategoryName] like &apos;%dynamic%&apos; &lt;/sql&gt;&lt;/customobject&gt;&lt;customobject&gt;&lt;properties&gt;&lt;property&gt;&lt;symname&gt;RecordFolderName&lt;/symname&gt;&lt;displayname&gt;Record Folder Name&lt;/displayname&gt;&lt;propertytype&gt;8&lt;/propertytype&gt;&lt;selectable&gt;true&lt;/selectable&gt;&lt;value&gt;dynamic&lt;/value&gt;&lt;operator&gt;like&lt;/operator&gt;&lt;jointype&gt;AND&lt;/jointype&gt;&lt;/property&gt;&lt;/properties&gt;&lt;aggregation&gt;RecordFolder&lt;/aggregation&gt;&lt;sql&gt; SELECT ro.[RecordFolderName] , ro.[RecordFolderName] FROM RecordFolder ro Where ro.[RecordFolderName] like &apos;%dynamic%&apos; &lt;/sql&gt;&lt;/customobject&gt;&lt;/objectset&gt;&lt;/response&gt;" />
           <Property Name="HoldType" Value="Audit" />
       </Properties>
    </RMEntity>
</Holds>

Retention period update

To update the retention period of an existing phase to null, the retention period properties (RetentionPeriodYears, RetentionPeriodMonths and RetentionPeriodDays) need to be included in the XML file with no value.

Below is a sample XML of a phase entity for the File Plan Import Export tool:

<RMEntity Type="Phase" Name="phase 1">
                  <Properties>
                        <Property Name="PhaseAction"></Property>
                        <Property Name="PhaseNumber" Value="1" />
                        <Property Name="ExportFormat"></Property>
                        <Property Name="IsScreeningRequired" Value="false" />
                        <Property Name="DisposalSchedulePtr">
                              <ObjectRef ClassId="DisposalSchedule" ObjectId="mySchedule" />
                        </Property>
                        <Property Name="PhaseName" Value="phase 1" />
                        <Property Name="RMEntityDescription" />
                        <Property Name="RetentionPeriodMonths" />
                        <Property Name="RetentionPeriodYears"  />
                        <Property Name="RetentionPeriodDays"  />
                        <Property Name="AlternateRetentions">
                              <ObjectValue Type="AlternateRetention">
                                    <Properties>
                                          <Property Name="RetentionBase" Value="CutoffDate" />
                                          <Property Name="ConditionXML" Value="&lt;response xmlns=&quot;http://filenet.com/namespaces/wcm/apps/1.0&quot;&gt;&lt;objectset&gt;&lt;count&gt;1&lt;/count&gt;&lt;customobject&gt;&lt;properties&gt;&lt;property&gt;&lt;symname&gt;CurrentActionType&lt;/symname&gt;&lt;operator&gt;IS EQUAL&lt;/operator&gt;&lt;value&gt;6&lt;/value&gt;&lt;/property&gt;&lt;/properties&gt;&lt;aggregation&gt;&lt;/aggregation&gt;&lt;sql&gt; AND ([CurrentActionType] = 6)&lt;/sql&gt; &lt;/customobject&gt;&lt;/objectset&gt;&lt;/response&gt;" />
                                          <Property Name="RetentionPeriodMonths" Value="0" />
                                          <Property Name="RetentionPeriodYears" Value="2" />
                                          <Property Name="RetentionPeriodDays" Value="0" />
                                    </Properties>
                              </ObjectValue>
                        </Property>
                  </Properties>
            </RMEntity>