Use an external ID to identify objects during import

When objects are maintained in an external system and are re-imported regularly to update the existing objects in the Content Store but the external system cannot guarantee consistent filenames on export, you must use an identifier (an external ID) to match the object being imported to the existing object in the Content Store.

Normally, when a topic is imported, the system stores the original filename of the object and uses it to identify the object if the same object is re-imported in the future. When the external system cannot guarantee consistent filenames on export, then another identifier must be used. Since this other identifier depends on what the external system produces, your solution will be specific to your system.

The identifier must be specified in the objects in a consistent manner and must be unique and be selectable by an XPath expression. Ideally, the identifier should be specified in the DITA objects using the <resourceid appname="external_id" id="[ID]"></resourceid> element where appname="external_id" identifies the use of the identifier (which remains the same in all the objects and "external_id" is the recommended value) and [ID] is the identifier (which uniquely identifies the object).

To use the identifier instead of the filename, you need to edit the importManager.xml configuration file to define the XPath required to find the identifier in the objects and then specify an index for it in the Index Definition file.

Restriction: Only one XPath expression is supported.

For example, suppose that your external system is used to maintain a parts list. The external system exports the parts list as DITA reference topics which must be regularly imported into the Content Store to update the existing reference topics. Unfortunately, the external system does not provide consistant filenames, but provides an identifier that is added to the topics as resource IDs as follows:

<reference id="mwa1514927693019" xml:lang="en-us">
  <title ixia_locid="1">MOD. MX6000C</title>
  <prolog>
    <resourceid appname="external_id" id="zpl1518121396268"></resourceid>
  </prolog>
  <refbody>
. . .

In the importManager.xml configuration file, you define the Xpath expression to specify the identifier; for example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE importManager PUBLIC "-//ixiasoft.com//cms//config//importManager" "importManager.dtd">
<importManager>
	<!-- Defines the XPath required to locate the identifier (an external ID) in objects being imported. 
	This is used when objects are maintained in an external system that cannot guarantee consistent filenames on export. -->
	  
	<external-id-path>
		<location  xpath="//resourceid[@appname='external_id']/@id"/>
	</external-id-path>	
</importManager>

In the Index Definition, you define the index using the same XPath expression; for example:

<index  NAME="externalId">
   <stringindex KEEPEXTRACTEDVALUES="True">
      <elements>
         <element DEPTH="0" XPATH="//resourceid[@appname='external_id']/@id"/>
      </elements>
   </stringindex>
</index>

When the use of external IDs is enabled, non-DITA files such as resource objects (for example, SVG and MathML) continue to be identified by their original filename. For non-XML files such as images, the original filename will be stored as the external ID.

When the use of external IDs is enabled, the import process systematically checks if an existing object in the Content Store already has the same identifier (stored as the external ID). If a file being imported has an identifier that already exists in the Content Store, the existing object with the matching identifier is updated with the imported file only if the Update existing documents option is selected; otherwise the import fails. If more than one object is found in the Content Store with the same identifier as the file being imported (for example, as a result of the existing object being cloned), the import fails.

To enable the support for an external ID:

Open the TEXTML Administration perspective by clicking the TEXTML Administration shortcut on the tool bar. If the shortcut is not displayed, follow these steps:
1. Select Window > Perspective > Open Perspective > Other
2. Click TEXTML Administration.
3. Click Open.
In the TEXTML Administration view, double-click the server. If your server is not displayed in the view, you must add it to the view.
When the Connect as dialog opens, type your username and password and click OK.
Double-click the name of your Content Store to open a connection to it.
Locate the importManager.xml file in the repository's /system/conf collection.
Right-click the file and click Check Out.
Double-click the file to open it in the editor.

Remove the comment symbols () from around the external-id-path element.

For example, delete the symbols shown in bold:

<importManager>
	<!-- Defines the XPath required to locate the identifier (an external ID) in objects being imported. 
	This is used when objects are maintained in an external system that cannot guarantee consistent filenames on export. -->
	<!--  
	<external-id-path>
		<location  xpath="//resourceid[@appname='external_id']/@id"/>
	</external-id-path> -->	
</importManager>

In the xpath attribute, delete the example XPath expression and replace it with your XPath expression.
For example, replace the XPath expression highlighted in bold:
```
<external-id-path>
	<location  xpath="//resourceid[@appname='external_id']/@id"/>
</external-id-path>
```
When you are done, save, close, and check in the importManager.xml file.
Expand the Content Store node and locate the Index Definition document.
Right-click the file and click Check Out.
Double-click the file to open it in the XML editor area.

Locate the externalId index.

For example:

<index  NAME="externalId">
   <stringindex KEEPEXTRACTEDVALUES="True">
      <elements>
         <element DEPTH="0" XPATH="//resourceid[@appname=external_id']/@id"/>
      </elements>
   </stringindex>
</index>

Replace the example XPath expression in the xpath attribute with the same expression defined in the importManager.xml file.
For example, replace the XPath expression highlighted in bold:
```
<element DEPTH="0" XPATH="//resourceid[@appname=external_id']/@id"/>
```
When you are done, save, close, and check in the Index Definition document.