Use an external ID to identify objects during import

You must use an external identifier (ID) to match the object imported from an external system to the existing object in the Content Store.

Normally, when you import an object, the system stores the original filename of the object and uses it to identify the object for future re-imports of the same object. When the external system cannot guarantee consistent filenames during export, then you must use an identifier. Since this alternate identifier depends on your external system and its own processes, your solution is system-specific.

You must specify an object identifier in a consistent manner that is both unique and selectable by an XPath expression. Ideally, you specify the identifier 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 where "external_id" is the recommended value, and where [ID] is the identifier that uniquely identifies the object.

Important: Make configuration changes in a test environment and confirm they work before copying them to a production environment. For dedicated SaaS deployments, test the changes and then ask IXIASOFT Customer Support to copy the changes to your production environment.

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, as in the following example.

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

When you enable the use of external IDs, the import process systematically determines if an existing object in the Content Store already has the same identifier, which is stored as the external ID. If a file being imported has an identifier that already exists in the Content Store, then the existing object with the matching identifier is updated with the imported file only if you select the Update existing documents option. Otherwise, the import fails. If more than one object is found in the Content Store with the same identifier as the import file, the import fails. This often occurs as a result of cloning the existing object.

Important: If you choose to use an external ID to identify objects during import, the CCMS cannot also match objects based on filename or file path. It only uses the external ID method, and objects without an external ID are considered new.

When you enable the use of external IDs, non-DITA files such as SVG and MathML resource objects still are identified by their original filename. For non-XML files such as images, the original filename is stored as the external ID.

To use an external ID to identify objects during import:

In the TEXTML Administration perspective, connect to your server.
Locate the importManager.xml file in the repository's /system/conf collection.
Check out the file and open it for editing.

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>
```
Save, close, and check in the file.
Locate the Index Definition document.

CAUTION: Be careful when editing the Index Definition document. Changes can significantly affect the indexing process, and any errors in the document can lead to data corruption or other errors. Consult with IXIASOFT Customer Support before making changes if you are unsure.

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"/>
```
Save, close, and check in the file.
Inform users of the changes.
The changes will be applied automatically once users close and then reopen their IXIASOFT CCMS Desktop. Users can also apply the changes without restarting their CCMS Desktop by clicking IXIASOFT CCMS > Synchronize Configuration.

The external ID used to match the object imported from an external system to the existing object in the Content Store is added.