IBM Enterprise Records, Version 5.1.2    

Troubleshooting File Plan Import Export tool

You need to know the information about the common causes of errors that you might encounter when using the IBM® Enterprise Records File Plan Import Export tool. You also need to know 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 you do not see any message. The cause of the error might be any of the following issues: The File Plan Import Export tool includes options that you can use to address potential errors. Learn more about these options in the following sections.

Manually creating an XML file

Manually creating an XML file means creating an XML file without using 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, create an XML file that is both compliant with the XML standard and compatible with the 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.

Important: Most of the errors that occur while importing a file plan are caused by incompatible or non-compliant XML files. Therefore, be careful if you manually create an XML file.

After you manually create an XML file, 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. For details about the validate mode, see the using the file plan tool topic.

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

Observing the File Plan Import Export tool functions

To manually create an XML file to import a large file plan with custom classes and objects, first create a small file plan and related metadata. Then run the tool in export mode. Such an exercise is useful before you manually create an XML file for file plans with conditional holds, internal event triggers, and alternate retention objects. All of these actions contain the complex ConditionXML property. Even though you create a file with the correct XML format, the XML file might have incorrect property values or syntax. This incorrect information might cause an error during importation. You can review the XML file that the tool creates when you export a small file plan. Review the XML file to see 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. For information about the procedures for using the scope metadata option, see the using the file plan tool topic.

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 might want to use the Skip option. During the second attempt at importing the same file plan, use the Skip option to avoid 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, you want to use the Replace option.

During subsequent importations of minor modifications to few entities, specify Action="Modify" in the XML file for the entities, instead of changing 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 IBM Enterprise Records user interface 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, specify that the subcategory does not inherit the schedule of the parent. Specify that the subcategory provides 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:
<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. The File Plan Import tool uses this property to import the following items: 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 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. The standard representation is &lt;, &gt;, &amp;, &quot;, and &apos;. See the sample XMLs of entities containing ConditionXML property for File Plan Import Export in the following sections.

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" />
          <ObjectValue Type="AlternateRetention">
            <Properties>
              <Property Name="RetentionBase" Value="CutoffDate" />
              <Property Name="ConditionXML" Value="&lt;response xmlns=&quot;http://www.ibm.com/namespaces
              /wcm/apps/1.0&quot;&gt;&ltobjectset&gt;&ltcount&gt;1&lt
              /count&gt;&ltcustomobject&gt;&ltproperties&gt;&ltproperty&gt;&ltsymname&gt;ClosedBy&lt
              /symname&gt;&ltoperator&gt;IEQUAL&lt;/perator&gt;&ltvalue&gt;Administrator&lt/value>
              </property></properties><aggregation></aggregation><sql> AND ([ClosedBy] = 'Administrator')
              </sql> </customobject></objectset></response>" />
              <Property Name="RetentionPeriodMonths" Value="0" />
              <Property Name="RetentionPeriodYears" Value="5" />
              <Property Name="RetentionPeriodDays" Value="0" />
            </Property>
          </ObjectValue>
          <ObjectValue Type="AlternateRetention">
            <Properties>
              <Property Name="RetentionBase" Value="DateClosed" />
              <Property Name="ConditionXML" Value="&lt;response xmlns=&quot;http://www.ibm.com/namespaces
              /wcm/apps/1.0&quot;&gt;&ltobjectset&gt;&ltcount&gt;1&lt
              /count&gt;&ltcustomobject&gt;&ltproperties&gt;&ltproperty&gt;&ltsymname&gt;
              RMEntityDescription&lt/symname&gt;&ltoperator&gt;LKE&lt;/perator&gt;&ltvalue&gt;something&lt
              /value></property></properties><aggregation></aggregation><sql> AND ([RMEntityDescription] 
              LIKE '%something%')</sql> </customobject></objectset></response>" />
              <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://www.ibm.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://www.ibm.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. See a sample XML of a phase entity for the File Plan Import Export tool in the following example:
<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://www.ibm.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>


Feedback

Last updated: November 2013
file_plan_import_export_tips.htm

© Copyright IBM Corporation 2013