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, 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.

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 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.

Note: You should make these configuration changes in the Test environment and test them before copying them to the Production environment. In a dedicated SaaS deployment, after testing the changes, ask IXIASOFT Customer Support to copy the changes to the Production environment.

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.