Instructions

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/5.0"
          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.)

Type	Description	Resulting labeling in the deskclient	Preconditions	Example
publish	The 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') . The variant with the versionParameters child node adds the mentioned version parameters as metadata for the publication process. Read the documentation of the document lifecyle for more information about version parameters and their usage.	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" /> or <lifecycleActivity type="publish">   <versionParameters>      <versionParameter name="foo" />      <versionParameter name="bar" />   </versionParameters> </lifecycleActivity>
finishPrePublishing	The 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" />
release	The 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" />
setOffline	The imported document will be set offline.		The document is not deleted, is not offline already and has a live version.	<lifecycleActivity type="setOffline" />
delete	The imported document will be deleted.		The document is not deleted already.	<lifecycleActivity type="delete" />
deletePermanently	The imported document will be deleted permanently.		The document is in the trash bin.	<lifecycleActivity type="deletePermanently" />
restore	The imported document will be restored.		Document is deleted.	<lifecycleActivity type="restore" />
createVersion	Creates 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" />
keepState	Preserves 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/5.0"
          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:

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/5.0"
          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:

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