About external IDs

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 specify an identifier.

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

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

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.