Import XML | Version 3

Instructions

How to use Instructions to define actions that are executed when a document is imported.

Archived documentation for Sophora 3. End-of-support date for this version: 7/25/21

Documentation for Sophora 4

Instructions (<instructions>) can be used to define actions that are executed when a document is imported, irrespective of the fact whether a new document is created or an existing one is updated.

Possible use cases for instructions may be to add a document to one or more proposal section(s) or to publish it immediately.

The different instructions can only be executed, if the fundamental import is successful.

Instructions Concerning a Document's Life Cycle (Publishing, Deletion etc.)

For every document to import you can define life cycle concerning actions. Each of these actions has to be provided via a <lifecycleActivity> element. Such element requires the "type" attribute to be specified.

<lifecycleActivity> elements are placed within the <lifecycleActivities> element. You can define as many activities as you want. They will be performed in the order in which you put them in the XML. The following example shows the common case of publishing a document after importing it:

<?xml version="1.0" encoding="UTF-8"?>
<document nodeType="sophora-content:story"
          xmlns="http://www.sophoracms.com/import/2.8"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <properties>
    [...]
  </properties>
  <childNodes>
    [...]
  </childNodes>
  <resourceList>
    [...]
  </resourceList>
  <fields>
    [...]
  </fields>
  <instructions>
    <lifecycleActivities>
      <lifecycleActivity type="publish" />
    </lifecycleActivities>
    <proposals />
    <stickyNotes />
  </instructions>
</document>

In the table below, all possible value for the type attribute are given. (It doesn't matter whether the import created a new document or was an update of an existing document.)

TypeDescriptionResulting labeling in the deskclientPreconditionsExample
publishThe imported document will be published respectively put to the state 'publishAt' (if a 'publishAt'-Date is set) or to the state 'prePublished' (if the document type of the document has the sophora mixin 'prePublishRequired') . or or The document is not deleted, is not in the state 'prePublished' and this very version of the document is not online already.<lifecycleActivity type="publish" />
finishPrePublishingThe imported document will be published, also if it is in the state 'prePublished'. or The document is not deleted and this very version of the document is not online already.<lifecycleActivity type="finishPrePublishing" />
releaseThe imported document will be released. The document is not deleted, is not released already or in the state 'publishAt' or 'prePublished' and this very version of the document is not online already.<lifecycleActivity type="release" />
setOfflineThe imported document will be set offline. The document is not deleted, is not offline already and has a live version.<lifecycleActivity type="setOffline" />
deleteThe imported document will be deleted. The document is not deleted already.<lifecycleActivity type="delete" />
deletePermanentlyThe imported document will be moved from the trash bin to the delete archive respectively deleted permanently (depending on your server configuration). The document is in the trash bin.<lifecycleActivity type="deletePermanently" />
restoreThe imported document will be restored. Document is deleted.<lifecycleActivity type="restore" />
createVersionCreates a version of the given document.Does not affect the status of the document.Document is in working state and was altered since its last versioning.<lifecycleActivity type="createVersion" />
keepStatePreserves the previous state of the document.Depends on previous state.None.<lifecycleActivity type="keepState" />
keepState (with fallback)A fallback activity can be defined for the keepState activity, in case the document does not already exist. A fallback activity can be any lifecycle activity except for keepState.Depends on previous state.None.<lifecycleActivity type="keepState" fallback="publish" />

The subsequent example displays a (slighty made-up) example where the imported document will be completed, published twice, set offline, deleted and restored again:

<?xml version="1.0" encoding="UTF-8"?>
<document nodeType="sophora-content:story"
          xmlns="http://www.sophoracms.com/import/2.8"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <properties>
    [...]
  </properties>
  <childNodes>
    [...]
  </childNodes>
  <resourceList>
    [...]
  </resourceList>
  <fields>
    [...]
  </fields>
  <instructions>
    <lifecycleActivities>
      <lifecycleActivity type="release" />
      <lifecycleActivity type="publish" />
      <!-- This action is not possible, because the document is published already: -->
      <lifecycleActivity type="publish" />
      <lifecycleActivity type="setOffline" />
      <lifecycleActivity type="delete" />
      <lifecycleActivity type="restore" />
    </lifecycleActivities>
    <proposals />
    <stickyNotes />
  </instructions>
</document>

The third activity (the second "publish") doesn't break down the whole process but rather produces a warning that the document could not be published again. The subsequent activities are executed properly.

Adding a Document to Proposal Sections

For every imported document you can create one or more proposals. Each proposal can be sent to several proposal sections. The XML fragment for a single proposal looks like this:

<proposal startDate="2009-08-20T09:00:00+02:00" endDate="2009-09-20T09:00:00+02:00">
  <proposalSections>
    <proposalSection priority="LOW">
      <path>Politik</path>
      <path>Inland</path>
    </proposalSection>
  </proposalSections>
  <comment>Bitte schnellstmöglich bearbeiten.</comment>
  <sender>mueller</sender>
</proposal>

The following table summarises the possible elements and attributes of this XML part:

Element/AttributeMandatoryDescriptionExample
<proposal>NoThe root element for a proposal. It has to be placed within the <proposal> element.<proposal endDate="2009-09-20T09:00:00+02:00">
 [...]
</proposal>
startDate (attribute)NoDetermines when a document starts being offered in the proposal section. Format: "ISO 8601"startDate=
"2009-08-20T09:00:00+02:00"
endDate (attribute)NoDetermines when a document stops being offered in the proposal section. Format: "ISO 8601"endDate=
"2009-09-20T09:00:00+02:00"
newDocumentProposal (attribute)NoThis attribute defines whether only newly created documents are proposed. Is this attribute true (or "1"), no proposal is created, if the import just updates an existing document. Default value is false.newDocumentProposal="true"
<proposalSections>YesContains the proposal sections where the document will be offered.<proposalSections>
  [...]
</proposalSections>
<proposalSection>YesDefines the individual proposal section. This element is required at least one time.<proposalSection>
  [...]
</proposalSection>
<path>YesThe <path> elements within <proposalSection> specify the path of the proposal section.<proposalSection>
  <path>Politik</path>
  <path>Inland</path>
</proposalSection>
priority (attribute)NoAttribute of the <proposalSection> element. It specifies the priority of the proposal within a particular section. Supported values: "LOW", "MEDIUM", "HIGH". It defaults to "MEDIUM" if not present.<proposalSection priority="HIGH">
<comment>NoA comment about this proposal. This element may be empty.<comment>Bitte schnellstmöglich bearbeiten.</comment>
<sender>NoThe originator of this proposal which has to be a valid Sophora user from the repository. If this element is omitted, the user who connected the Importer with the repository is used instead.<sender>mueller</sender>

The subsequent example presents a document where three different proposals will be created after importing. The first proposal is placed in two different proposal sections ("Mediathek" and "Marktplatz/Medien") whereas the other two proposals are assigned to only one proposal section each ("Sport" and "Team Kultur/Ausstellungen" respectively). Various priorities are assigned to proposals in different sections.

<?xml version="1.0" encoding="UTF-8"?>
<document nodeType="sophora-content:story"
          xmlns="http://www.sophoracms.com/import/2.8"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <properties>
    [...]
  </properties>
  <childNodes>
    [...]
  </childNodes>
  <resourceList>
    [...]
  </resourceList>
  <fields>
    [...]
  </fields>
  <instructions>
    <lifecycleActivities />
    <proposals>
      <proposal startDate="2009-08-20T09:00:00+02:00" endDate="2009-09-20T09:00:00+02:00">
        <proposalSections>
          <proposalSection priority="HIGH">
            <path>Mediathek</path>
          </proposalSection>
          <proposalSection>
            <path>Marktplatz</path>
            <path>Medien</path>
          </proposalSection>
        </proposalSections>
        <comment>Bitte schnellstmöglich bearbeiten.</comment>
        <sender>mueller</sender>
      </proposal>
      <proposal endDate="2009-09-23T09:00:00+02:00">
        <proposalSections>
          <proposalSection priority="MEDIUM">
            <path>Sport</path>
          </proposalSection>
        </proposalSections>
      </proposal>
      <proposal>
        <proposalSections>
          <proposalSection priority="LOW">
            <path>Team Kultur</path>
            <path>Austellungen</path>
          </proposalSection>
        </proposalSections>
      </proposal>
    </proposals>
    <stickyNotes />
  </instructions>
</document>

Sticky Notes of a Document

Sticky notes can also be created, edited and removed when importing a document.

The XML fragment to add or edit a sticky note looks like this.

<stickyNote stickyNoteId="my-sticky-note" >This is an important message.</stickyNote>

If a sticky note with the given ID already exists for the document it will be overwritten with the one from the XML. Otherwise a new sticky note with the given ID will be created.

To remove a sticky note from a document via the importer you will have to use the remove attribute:

<stickyNote stickyNoteId="my-sticky-note" remove="true"></stickyNote>

The following table summarises the possible attributes of this XML part:

AttributeMandatoryDescriptionExample
stickyNoteIdYesThe ID of the sticky note to add/edit/remove.stickyNoteId="my-sticky-note"
colorNoThe background color of the sticky note. Must be of the format "red,green,blue", where the three values are integers in the range 0-255.color="255,255,0"
removeNoIf set to "true" the sticky note will be removed from the documentremove="true"

The subsequent example presents a document where three different sticky notes will be added, edited and removed. As you may notice the sticky note elements to add and edit a sticky note look exactly the same. Editing a sticky note will be determined by checking if it already exists in the document. This is an internal process.

<?xml version="1.0" encoding="UTF-8"?>
<document nodeType="sophora-content:story"
          xmlns="http://www.sophoracms.com/import/3.3"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <properties>
    [...]
  </properties>
  <childNodes>
    [...]
  </childNodes>
  <resourceList>
    [...]
  </resourceList>
  <fields>
    [...]
  </fields>
  <instructions>
    <lifecycleActivities />
    <proposals />
    <stickyNotes>
        <stickyNote stickyNoteId="new-sticky-note" >New Sticky Note</stickyNote>
        <stickyNote stickyNoteId="edit-sticky-note" color="123,123,123" >Edited Sticky Note</stickyNote>
        <stickyNote stickyNoteId="delete-sticky-note" remove="true" ></stickyNote>
    </stickyNotes>
  </instructions>
</document>

Last modified on 10/2/20

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

Icon