The Observation module allows applications to register interest in events or changes to a workspace. Event listeners monitor changes and when a persistent change is detected, a defined response is triggered.
Event listeners are useful for defining automatic behavior and can be used in many instances. Commonly used examples include automatic activation, deactivation and sending mail. A customized listener can be configured to respond to almost any event.
- Default EE installation
- Listener properties
- Command and class properties and parameters
- Example: Automatic activation of DMS documents
Observation is a community module. It is not bundled with either the Community or Enterprise Edition by default and should be downloaded and installed individually. To check whether it is installed, go to Magnolia Store > Installed modules in AdminCentral.
See the general module uninstalling instructions and advice.
Default EE installation
The Observation module is typically not installed by default, but the Configuration >
/modules/observation folder exists. The folder contains two sample event listener configurations:
These configurations are installed by the Commenting and Categorization modules respectively and are provided as examples. They do not work if the Observations module is not installed.
All listeners depend on the underlying functionality of the Observation module. When you install the Observation module, the sample configurations will be overridden by different ones. These are useful configurations so before installing the Observation module, export
generateCategories to XML for use at a later stage. For more information about these samples, please see:
Two types of event listeners are supported:
- Listeners that specify a command to be executed when an event occurs.
- Listeners that use their own event listener class.
activateAddedPages. Both are examples of a listener that executes a command. The only configuration difference is that when configuring a listener that has its own listener class, you don't need the
/paramsnodes. For an example of the listener class type, see PageListener sample below.
An event listener configuration has the following node structure.
This is an example of a listener configuration. The
sendMailOnPageChanges listens to changes to pages and sends an email message as a result.
|Describes what the listener does.||
|Enables and disables the listener.||
|The type of event being listened to. There are five possible values: ||
|Workspace in which the event is monitored.||
|Path from which the event is triggered.||
|Optional. Allows subnodes to be included or excluded by the listener. If the property is left out, subnodes are monitored by default. If the property is included, subnodes are not monitored unless set to ||
|Optional. Delay in milliseconds before the listener is triggered.||
|Optional. Maximum delay milliseconds before the listener is triggered.||
Command and class properties and parameters
The following properties are specific to the command triggered in response to the event or the class executed.
|Fully qualified name of a custom event listener class or the class enabling the triggering of the command. For commands, two classes are provided (see below).||
|Optional. Limits monitoring to a single node type. By default, all node types are monitored.||
|Fully qualified name of the command executed.||
|Workspace in which the command is executed.||
|Optional. Parameters sent to the command as determined by the command class. Not all commands allow for parameters.||
Out of the box, two classes are provided for use with commands:
RestrictToNodeTypeEventListenerimplements the restrict path to node type behavior class.
RegexEventListenerfilters events based not only on the node type, but also on a regular expression pattern. Only events where the path matches the regexp pattern are processed and execute the specified command. The configuration requires an additional property
/listener/regexthat specifies the pattern.
A single listener can monitor a single
nodeType or all types. To monitor two types to the exclusion of other types, two listener configurations are required. Folders and files, for example, require one listener to monitor folders (
nodeType=mgnl:content) and another to monitor files (
nodeType=mgnl:contentNode). You can verify the
nodeType by exporting the node to be monitored to XML and searching for the value of
jcr:primaryType property in the file.
The module includes an example listener Java class
PageListener. You can find it in the module .jar at
/info/magnolia/module/observation/sample/PageListener. This is a basic example that prints a message to the console.
The configuration below uses the
PageListener class and demonstrates the most basic configuration for a listener that uses its own event listener class.
When you add a new page to
/demo-project in the Website workspace, an alert is displayed in the console.
Example: Automatic activation of DMS documents
The Observation module installs an example listener
activateAddedPages. It listens to the
NODE_ADDED event in the
website workspace, which means new pages being added, activates them automatically. The listener configuration is in Configuration >
In this example we modify
activateAddedPages to monitor the
dms workspace instead. We invoke the
ActivationCommand to activate any new files added to the
/demo-project/downloads folder. If editors on your site frequently forget to activate DMS assets used on Web pages, this listener may help.
activateAddedPages configuration as follows:
- Copy the
activateAddedPagesnode and name the copy
trueto enable the listener.
descriptionto describe what the listener does.
To test, upload a new file to
dms:/demo-project/downloads. It will be activated automatically to the public instance.