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/2.8"
          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/2.8"
          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/2.8"
           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>>

Referencing Existing Documents by xPath Expression

In some situations you may need a more flexible mechanism to reference existing documents than just identifying them by external ID. For this purpose you can declare arbitrary xPath expressions, which you must provide with a unique 'idString'. The importer resolves the xPath expressions and replaces every occurrence of the 'idString' with the external ID(s) of the xPath expression result(s).

A xPath expression is declared in the special element <documentIdentificationExpression> which is a direct child of the element <documentIdentificationExpressions>. The latter is the optional first Element of the element <documents>.

The first example shows the update of a document with the sophora id 'broadcastimage142':

<?xml version="1.0" encoding="UTF-8"?>
<documents xmlns="http://www.sophoracms.com/import/2.8" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <documentIdentificationExpressions>
    <documentIdentificationExpression idString="$externalId1$">element(*, sophora-content-nt:imageobject)[@sophora:id = 'broadcastimage142']</documentIdentificationExpression>
  </documentIdentificationExpressions>
  <document externalID="$externalId1$">
    <properties>
      [...]
    </properties>
    <childNodes>
      [...]
    </childNodes>
    <resourceList />
    <fields>
      [...]
    </fields>
    <instructions>
      [...]
    </instructions>
  </document>
</documents>

If you wish to reference an existing document from the repository as a childnode or as a reference property, provide the 'idString' of the xPath expression element in the corresponding reference property. To include an existing image (with a sophora id of 'broadcastimage142') in a newly created image gallery, the XML should contain the following snippet:

<?xml version="1.0" encoding="UTF-8"?>
<documents xmlns="http://www.sophoracms.com/import/2.8" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <documentIdentificationExpressions>
    <documentIdentificationExpression idString="$externalId1$">element(*, sophora-content-nt:imageobject)[@sophora:id = 'broadcastimage142']</documentIdentificationExpression>
  </documentIdentificationExpressions>
  <document>
    <properties>
      [...]
    </properties>
    <childNodes>
      <childNode nodeType="sophora-content-nt:imageref" name="sophora-content:image">
        <properties>
          <property name="sophora:reference">
            <value>$externalId1$</value>
          </property>
        </properties>
        <childNodes/>
        <resourceList />
      </childNode>
    </childNodes>
    <resourceList/>
    <fields>
      [...]
    </fields>
    <instructions>
      [...]
    </instructions>
  </document>
</documents>

The last snippet shows a more complex example: Every story document (i.e. the node has the type 'sophora-content-nt:story') with the headline 'Test' (see first element <documentIdentificationExpression>) is updated by setting it's headline to the value 'A real headline'. Additionally a 'teasersInTeaser' childnode is set at every of this story documents which points to the story with the sophora id 'teaserinteaser100' (see second element <documentIdentificationExpression>):

<?xml version="1.0" encoding="UTF-8"?>
<documents xmlns="http://ww.sophoracms.com/import/2.8">
  <documentIdentificationExpressions>
    <documentIdentificationExpression idString="$externalId1$" maxNumberOfResults="unbounded">element(*, sophora-content-nt:story)[@sophora-content:headline = 'Test']</documentIdentificationExpression>
    <documentIdentificationExpression idString="$externalId2$">element(*, sophora-content-nt:story)[@sophora:id = 'teaserinteaser100']</documentIdentificationExpression>
  </documentIdentificationExpressions>
  <document externalID="$externalId1$">
    <properties>
      <property name="sophora-content:headline">
        <value>A real headline</value>
      </property>
    </properties>
    <childNodes>
      <childNode nodeType="sophora-content-nt:teaserRef" name="sophora-content:teasersInTeaser">
        <properties>
          <property name="sophora:reference">
            <value>$externalId2$</value>
          </property>
        </properties>
        <childNodes />
        <resourceList />
      </childNode>
    </childNodes>
    <resourceList />
    <fields>
      [...]
    </fields>
    <instructions>
      [...]
    </instructions>
  </document>
</documents>

The following table explaines the element <documentIdentificationExpression> in details - mandatory content is marked as bold: