Referencing Existing Documents

Referencing existing documents by external ID

When importing documents you can also connect them with documents that already exist in the repository.

If you want to update an existing document, simply specify the document external ID as attribute (externalID) of the main <document> element. Note that the nodeType property is not required when updating existing documents.

In the following example an existing document with the external ID "image4711" will be updated by the import:

<?xml version="1.0" encoding="UTF-8"?>
<document externalID="image4711"
          xmlns="http://www.sophoracms.com/import/5.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <properties>
    [...]
  </properties>
  <childNodes>
    [...]
  </childNodes>
  <resourceList />
  <fields>
    [...]
  </fields>
  <instructions>
    [...]
  </instructions>
</document>

If you wish to reference an existing document from the repository as a childnode, provide its external ID in the corresponding reference property of the childnode. To include an existing image (ID="image4711") in a newly created image gallery, the XML should contain the following snippet:

<?xml version="1.0" encoding="UTF-8"?>
<document xmlns="http://www.sophoracms.com/import/5.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <properties>
    [...]
  </properties>
  <childNodes>
    <childNode nodeType="sophora-content-nt:imageref" name="sophora-content:image">
      <properties>
        <property name="sophora:reference">
          <value>image4711</value>
        </property>
      </properties>
      <childNodes/>
      <resourceList />
    </childNode>
  </childNodes>
  <resourceList/>
  <fields>
    [...]
  </fields>
  <instructions>
    [...]
  </instructions>
</document>

Conditional Import: Importing a document only if it exists in the repository already

Sometimes you may want to import a document only if it exists in the repository already - otherwise the import of the document (and all dependent content in the resource list of the document) should be skipped.

To achieve this goal you can use the optional attribute importOnlyIfDocumentExists (default value: false) which is a direct attribute of the element <document>.

In the following example the documents with the external ids story4711 and story4711-image are only imported, if the external id story4711 exists in the repository already. However, the document with the external id story4811 is imported because it is not enclosed in the resource list of document story4711 but placed on the same XML level (underneath the element <documents>) as document story4711.

<?xml version="1.0" encoding="UTF-8"?>
<documents xmlns="http://www.sophoracms.com/import/5.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <document externalID="story4711"
            importOnlyIfDocumentExists="true">
    <properties>
      [...]
    </properties>
    <childNodes>
      [...]
    </childNodes>
    <resourceList>
      <document nodeType="sophora-content-nt:imageobject"
                externalID="story4711-image">
        [...]
      </document>
    </resourceList>
    <fields>
      [...]
    </fields>
    <instructions>
      [...]
    </instructions>
  </document>
  <document nodeType="sophora-content-nt:story"
            externalID="story4811">
    [...]
  </document>
</documents>>