Structure nodes are internally saved as documents of type sophora-nt:structureNode2 and will be exported as such. These documents should be used to import structure nodes.
It is also possible to import structure nodes in a special XML format. This is especially useful for easy creation of a new structure. The root element in this import XML file has to be <sophora>. This element contains the two child elements <structure> and <documents> (legacy) for the structure node information and for the structure node documents respectively. A structure node is connected with its structure node document via the external ID of the document. If no structure node document is given in the import XML, the Importer implicitly creates a new one.
<structure> with <documents> of type sophora-nt:structureNode2 is redundant. The <structure> element can be used to create a basic structure without further configuration in the documents.<structure> is no longer allowed. The structure node format shown here can only be created with Sophora XML versions up to 3.8.Sites and Structure Nodes
The elements <site> and <structureNode> are encapsulated by the <structure> element. Additionally to the attributes of a <structureNode> element, the <site> element has the attribute "url". Furthermore, a site contains images variants as childelements <imagevariant> which have to be provided with an image variant's external Id. If the site already exists, the image variants are replaced by those from the XML. This only happens when at least one image variant is given in the import XML. Otherwise the image variants of the existing site are kept.
In the following explanations about the structure import it will not be distinguished between site and structure. They are treated equally
Properties of Sites and Structure Nodes
The properties of sites and structure nodes are modeled as attributes in the Sophora XML. Solely the image variants are modeled as childelements. The table below gives an overview about the existing attributes.
| Attribute | Site | Structure node | Description |
|---|---|---|---|
| path |  | | The path, including the site. |
| menuText | | | This text appears in the menus of the deliveries. |
| url | |  | The URL of the site. |
| isActive | | | Defines whether the according menu item shall be displayed. |
| state | | | A structure node's state ("inProcess", "published" or "disabled"). |
| isLiveVersionAvailable | | | Whether a structure node has been published already. |
| redirectUrl | | | A redirect Url for this structure node. |
| redirectActive | | | Whether a redirection is activated or not. |
| structureNodeDocumentExternalId | | | The external ID of the structure node document. |
| hierarchyDocumentExternalId | | | The external ID of the hierarchy document. |
| defaultDocumentExternalId | | | The external ID of the index document. |
Ordering Structure Nodes in the XML
The order of the structure nodes has to be respected.
Structure node elements have to be specified according to the depth-first search principle. Structure nodes are created in the exact order in which they occure in the XML. Therefore, a child structure node cannot be created before its parent node.
Merging Structure Node Properties
When a structure node that already exists is imported, the properties given in the XML and in the repository are merged. An overview of the possible cases is given below. The new version of the structure node refers to the import XML and the old version is the one from the repository.
A property is set in the in the new version but not in the old: The property is set (initially) in the repository
A property already exists in the old version and a) the according attribute does not exist in the new version: The property will not be modified. b) the according attribute is present but contains an empty string: The property will be deleted.
A property exists in both the new and the old version: The property value in the repository will be overwritten by the new version's value.
Merging structure node documents works in the same way as the merge of common documents (see section Managing the Update Behaviour of Documents).
Merging Structures
With an import operation you cannot delete structure nodes. If a structure node from the repository does have childnodes but the import XML lacks these childnodes, they remain unmodified in the repository.
The Status of a Structure Node
The status of a new structure node depends on the status of its structure node document. If there is no structure node document, the structure node's status is taken. The decision is made according to the value of the attribute isLiveVersionAvailable of the <structureNode> element. Is it set to true, the structure node will be published.
The procedure implies that the structure after importing does not have the exact same status as the structure that has been exported. This is due to the export mechanism for structure nodes: While exporting a structure node its current status is exported as well. The last live version is not considered.
Importing Disabled Structure Nodes
It is possible to import disabled structure nodes. In that case the attribute state of a <structureNode> element has the value "disabled". If a structure node is enabled in the new version (the version that updates an existing document in the repsoitory ) but the old version is disabled, the structure node will be updated so that it is enabled afterwards.
Importing Stucture Nodes That Are Marked as Deleted
Structure nodes in Sophora cannot be deleted immediately. Instead, they are marked as deleted. The same happens to their structure node documents.
If you import a structure node that is marked as deleted in the repository, it will be recovered. If the new version of the structure node has no reference to a structure node document, a new one is created and referenced. However, if an external ID of the structure node document is provided in the new version and it matches the external ID of the old structure node document, the old structure node document is recovered as well. Subsequently, both structure node documents are merged (which works in the same way as normal documents; see above). This is only valid if no alternative rules are specified (see Managing the Update Behaviour of Documents\).
Referencing Documents
During the import operation the Importer tries to refer to the default document, to the structure node document and to the hierarchy document using corresponding UUIDs. If an according document does not exist (yet) in the repository, an external reference is established (using the external ID). As soon as the referenced document is imported the external reference is removed and the UUID is taken instead.
