Import XML: Protecting and unprotecting

How to to protect and unprotect a document via the attribute „protectionInstruction“.

Protecting and unprotecting Documents

It is possible via the optional attribute protectionInstruction at the element <document> to protect and unprotect a whole document in the same way as you are protecting and unprotecting properties. The possible values for protectionInstruction are:


Value	Description
`none`	If a document with the given external id already exists in the repository and if this document is protected, the import of the document cannot be executed and an import error is thrown. Skipping the attribute `protectionInstruction` has the same meaning as using the value `none`!
`unprotect`	If a document with the given external id already exists in the repository and if this document is protected, the protection will be removed and then the document's XML will be imported. After the import of the document, the protection will not be (re-)established.
`protect`	If a document with the given external id already exists in the repository and if this document is not protected (or if the document is newly created), the document's XML will be imported and then the document will be protected. If a document with the given external id already exists in the repository and if this document is protected, the import of the document cannot be executed and an import error is thrown.
`forceProtect`	The document's XML will be imported in any case and then the document will be protected.
`reprotect`	The document's XML will be imported in any case. If a document with the given external id had already existed in the repository and if this document was protected, the protection will be re-established. In any other case (document was not protected in the repository / document was newly created) the document will not be protected.

The follwing XML snippet shows the use case of forcing the imported document to be protected (no matter if it was protected before or not):

<?xml version="1.0" encoding="UTF-8"?>
<document nodeType="sophora-content:story" protectionInstruction="forceProtect" xmlns="http://www.sophoracms.com/import/2.8">
  <properties>
     [...]
  </properties>
  <childNodes>
     [...]
  </childNodes>
  <resourceList />
  <fields>
     [...]
  </fields>
  <instructions>
    [...]
  </instructions>
</document>

You can only protect documents of nodetypes which implement the mixin sophora-mix:protectable.

Protecting and unprotecting Childnodes

There are two ways to protect/unprotect childnodes:

On document level you can protect/unprotect childnodes via the name of the childnode.
On every level of the component tree you can protect/unprotect component boxes via the childnode id of the box.

Protecting and unprotecting Childnodes on Document Level

To protect/unprotect childnodes on document level via the name of the childnode you have to provide an element <childNode> inside an element <updateBehaviour> in the way it is described in chapter Managing the Update Behaviour of Documents. With the optional attribute protectionInstruction at the element <childNode> you can provide the wanted protection behaviour. Analogous to protecting/unprotecting properties (see chapter Protecting and unprotecting Properties) and protecting/unprotecting the whole document (see chapter Protecting and unprotecting Documents) there are five possible values for the attribute protectionInstruction:

The following example shows different protection use cases:

<document nodeType="sophora-content-nt:story" externalID="import_000001" xmlns="http://www.sophoracms.com/import/2.8">
 <properties>
 [...]
 </properties>
 <childNodes>
 <updateBehaviour>
 <!-- Remove the copytext in the repository (if it exists) and protect it after setting it new. -->
 <childNode name="sophora-content:copytext" behaviour="delete" protectionInstruction="forceProtect" />
 <!-- Merge the teaser images in the repository (if existing) with the teaser images in the XML and protect them after merging.
 (But: If the teaser images are already protected in the repository, the existing teaser images are not touched and the
 teaser images in the XML are ignored!) -->
 <childNode name="sophora-content:teaserImage" behaviour="merge" protectionInstruction="protect" />
 <!-- Remove the protection of the story teasers in the repository (if it exists) and set the story teasers from the XML. -->
 <childNode name="sophora-content:teaser" behaviour="delete" protectionInstruction="unprotect" />
 <!-- Remove the protection of the dynamic table in the repository (if it exists), remove all existing rows of the dynamic table
 and afterwards set the rows of the dynamic table from the XML. Protect the dynamic table if it was protected before. -->
 <childNode name="sophora-content:dynamictableRow" behaviour="delete" protectionInstruction="reprotect" />
 </updateBehaviour>
 <childNode nodeType="sophora-extension-nt:copytext" name="sophora-content:copytext">
 [...]
 </childNode>
 <childNode nodeType="sophora-content-nt:imageRef" name="sophora-content:teaserImage">
 [...]
 </childNode>
 <childNode nodeType="sophora-content-nt:storyRef" name="sophora-content:teaser">
 [...]
 </childNode>
 <childNode nodeType="sophora-content-nt:dynamictableRow" name="sophora-content:dynamictableRow">
 [...]
 </childNode>
 [...]
 </childNodes>
 [...]
</document>

Notice that using the attribute protectionInstruction at an element <updateBehaviour> has only effect for childnodes on document level!

Protecting and unprotecting Component boxes via Childnode Id

To protect/unprotect a component box in the component tree you have to provide the attribute protectionInstruction at the corresponding element <childNode>. This childnode must have a property sophora:childNodeId to match an existing box in the repository. If you don't provide a childnode id while using the protectionInstruction protect or forceProtect, the child node id will be created during the import process. Analogous to protecting/unprotecting childnodes via childnode name (see previous chapter), properties (see chapter Protecting and unprotecting Properties) and protecting/unprotecting the whole document (see chapter Protecting and unprotecting Documents) there are five possible values for the attribute protectionInstruction:

The following example shows different protection use cases:

<document nodeType="sophora-content-nt:story" externalID="import_000001" xmlns="http://www.sophoracms.com/import/2.8">
 <properties>
 [...]
 </properties>
 <childNodes>
 <!-- Remove the existing box with childnode id "-5896417165016167967" from repository, set this box from XML
 and protect it after setting it. -->
 <childNode nodeType="sophora-content-nt:storylist" name="sophora-content:box" protectionInstruction="forceProtect">
 <properties>
 <property name="sophora:childNodeId">
 <value>-5896417165016167967</value>
 </property>
 <property name="sophora-extension:title">
 <value>Box title</value>
 </property>
 </properties>
 <childNodes>
 <childNode nodeType="sophora-content-nt:storyref" name="sophora-extension:teaser">
 <properties>
 <property name="sophora:reference">
 <value>external_id_000001</value>
 </property>
 </properties>
 <childNodes />
 <resourceList />
 </childNode>
 </childNodes>
 <resourceList />
 </childNode>
 <!-- Create this box new (no childnode id is set!) and protect it. -->
 <childNode nodeType="sophora-content-nt:storylist" name="sophora-content:box" protectionInstruction="protect">
 <properties>
 <property name="sophora-extension:title">
 <value>Box title</value>
 </property>
 </properties>
 <childNodes>
 <childNode nodeType="sophora-content-nt:storyref" name="sophora-extension:teaser">
 <properties>
 <property name="sophora:reference">
 <value>external_id_000002</value>
 </property>
 </properties>
 <childNodes />
 <resourceList />
 </childNode>
 </childNodes>
 <resourceList />
 </childNode>
 <!-- Remove the existing box with childnode id "-5896417165016167968" from repository, set this box from XML
 and protect it after setting it. (But: If the box exists in the repository and is already protected
 in the repository, the existing box is not touched and the box in the XML is ignored!) -->
 <childNode nodeType="sophora-content-nt:storylist" name="sophora-content:box" protectionInstruction="protect">
 <properties>
 <property name="sophora:childNodeId">
 <value>-5896417165016167968</value>
 </property>
 <property name="sophora-extension:title">
 <value>Box title</value>
 </property>
 </properties>
 <childNodes>
 <childNode nodeType="sophora-content-nt:storyref" name="sophora-extension:teaser">
 <properties>
 <property name="sophora:reference">
 <value>external_id_000003</value>
 </property>
 </properties>
 <childNodes />
 <resourceList />
 </childNode>
 </childNodes>
 <resourceList />
 </childNode>
 </childNodes>
</document>

Technically it is possible to use the attribute protectionInstruction at any childnode where the property sophora:childNodeId can be set. But this makes little sense because the deskclient supports only the protection of boxes in the component tree - the protection of particular components is not possible.

The content of this page is licensed under the CC BY 4.0 License. Code samples are licensed under the MIT License.