Scheduling Document State Transitions

Scheduled Publication

A document can be set to be scheduled at a future date:

• Set the property "Publish at" (sophora:publishAt) of a document to a future date.
• Publish the document.
• The document is now in the publish-at state. When the publication-date is reached, the document is published automatically by the Sophora Server.
• The property sophora:startDate is not supported any more.

In addition, a document can also be scheduled to be set offline at a future date. This date is set in the property "Online to" (sophora:endDate) of a document.

See also the section Automated Publishing within the user guide.

Timing Action Scripts

The Timing Action scripts are a fully flexible mechanism to schedule custom actions on documents. These actions are realised by Groovy scripts. They are only executed on the Sophora Primary Server, not on the staging or replication Sophora Replica Servers. This section will give an overview of timing actions. For detailed information about the configuration of Timing Action scripts and examples, see the section on Scripts for Timing Actions.

Since 1.52, the functionality of the property sophora:offlineAfterDays is realized by timing actions. For "Offline after days" an action script is created by the update mechanic, when the server is started the first time.

Timing Actions

A Timing Action is defined by its configuration as described in the chapter Scripts for Timing Actions.

Generally, there are two different types of Timing Actions:

1. Timing Actions with a reference date property
2. Timing Actions without a reference date property

By both types it is also possible to define the reference date property in the corresponding script. An important part of the Timing Action is the script which specifies the action itself. Beyond the general configuration, a Timing Action consists of a relative period of time. This period of time is defined by the number of days relative to the reference date.

Execution of Timing Actions

The Timing Actions are triggered by a job which runs periodically on the Sophora Primary Server. The period is defined by a cron expression and can be configured in the sophora.properties file as well as via JMX. Furthermore, it is possible to immediately start the job via JMX. For each Timing Action, this job queries all documents for which the script is going to be executed.

Reference Date Properties

Considering the exemplary screenshots below, the "Custom Action 2" is configured in a way that a reference date property name can be defined for each node and content type. The reference date property name specifies a date property to which the configured number of days is relative. As by the other values, the reference date property names are inherited from the structure hierarchy. Thus, "Custom Action 2" for the node type sophora-content-nt:story is executed after 20 days relative to "Custom Date" for all documents of the node type sophora-content-nt:story except for those of the content type article. For such documents the action is executed after 10 days relatively to the version date (second screenshot).

If you specify a reference date property name in the structure node's Timing Action table and in the script as well, the one configured in the Timing Action table has priority.

If neither in the structure node's Timing Action table nor in the script a reference date property name is specified, the version date is taken as default.

Inheritance of Timing Actions

In general, Timing Actions are defined for structure nodes. They are automatically inherited to all child structure nodes as well as to all documents located at those structure nodes.

For example, look at the following timing configuration for the site demosite. Note that the actions "Custom Action 1" and "Custom Action 2" are, as their names imply, customised actions. The action "Days until offline" is predefined and managed by the Sophora Server. Their values are relative to the version date.

If content types are configured, the values can be specialised for each content type. The value for the node type is applied for all documents of the node type except of documents with a content type for which a specialised value exists. This includes also documents without any content type and documents with an invalid content type. A content type is invalid when it is registered in documents but does not exist anymore in the content type select value.

The structure node Home is a direct child structure node of the site demosite.

The inherited Timing Action values are displayed in a grey font. The values in the black font are overridden. As an example, the minus sign ('-') for the node type sophora-content-nt:story in the field of "Custom Action 2" interrupts the chain of inheritance. Hence, the "Custom Action 2" is not executed for any document which is located at the structure node /demosite/home or at any child structure node of /demosite/home. Unless the value is not overridden again in any subnode.

The value for documents of the node type sophora-content-nt:story and its content type article is overridden as well. Thus, the action is executed after 10 days relative to the version date for documents with these criteria and which are located recursively under the structure node /demosite/home.

Overriding Timing Actions in Documents

All Timing Actions configured in structure nodes can be overridden in individual documents. Please refer to the documentation of the corresponding input type field for this issue. Note that it is only possible to override the number of days in documents. It is not possible to override the reference date property for single documents.

State Changes of Documents

The following table contains possible actions on documents and their resulting status. These are a document's change-over states. The exact state a document has changed to can be obtained by the DocumentChangedEvent that is sent by the Sophora server.

Cron Server Feature

The Mixin sophora-mix:cronControl allows to set a document on- and offline periodically.

Overview

When the Mixin sophora-mix:cronControl is activated for a given node type, the properties

• sophora:cronNextOffDate (date)
• sophora:cronNextOnDate (date)
• sophora:cronOff (string)
• sophora:cronOn (string)

are available. The first both properties are for internal and debugging purposes only, whereas the third and the fourth accept a string in the Quartz cron format. A document will be published periodically depending on cronOn and it will be depublished (set offline) depending on cronOff. cronNextOffDate and cronNextOnDate will be updated every time such a transition between on- and offline occurs, which means:

1. cronNextOffDate reached ➔ set document offline ➔ delete cronNextOffDate and set cronNextOnDate ➔ set status to prePublished ➔ wait for cronNextOnDate
2. ➔ cronNextOnDate reached ➔ publish document ➔ delete cronNextOnDate and set cronNextOffDate ➔ wait for cronNextOffDate
3. continue with step 1.

Example

If you want to set a document with FSK 16 online only between 22:00 and 6:00, the properties have to be set as follows:

• sophora:cronOn = 0 0 22 1/1 * ? *
• sophora:cronOff = 0 0 6 1/1 * ? *

accordingly to the syntax described in http://www.quartz-scheduler.org/documentation/quartz-1.x/tutorials/crontrigger.

Take note

• When the cronNextOffDate is reached, the document is set offline, which means, e.g., its teaser will not be displayed on other sites.
• Listeners which are waiting for the event “document offline” will be notified.
• Any other date properties available for controlling the status of a document (e.g. online from, offline after) take precedence.
• It is not possible to publish documents initially by the cron. The documents have to be published first and then their status can be changed by the cron. This also means that a live version is needed for the cron to work.
• When the properties cronOff and cronOn should be set automatically accordingly to another property like the FSK, an additional script is required which sets the cron values.