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.

• Download
• Installing
• Uninstalling
• Configuration
• Default EE installation
• Types
• Structure
• Listener properties
• Command and class properties and parameters
• Commands
• Classes
• Example: Automatic activation of DMS documents

Download

Download the Observation module from Magnolia Store or Nexus repository.

Installing

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.

To install the module, please see the general module installation instructions. Enterprise Edition users, please read Default EE installation below before installing.

Uninstalling

See the general module uninstalling instructions and advice.

Configuration

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: sendMailOnPageComments and generateCategories.

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 sendMailOnPageComments and generateCategories to XML for use at a later stage. For more information about these samples, please see:

• Commenting: Observation
• Categorization: Observation.
• Mail: Observation.

Types

Two types of event listeners are supported:

1. Listeners that specify a command to be executed when an event occurs.
2. Listeners that use their own event listener class.

The Observation module includes two sample listeners sendMailOnPageChanges and 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 /listener/command and /params nodes. For an example of the listener class type, see PageListener sample below.

Structure

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.

Listener properties

Property	Description	Default Value
description	Describes what the listener does.	null
active	Enables and disables the listener.	false
eventTypes	The type of event being listened to. There are five possible values: NODE_ADDED, NODE_REMOVED, PROPERTY_ADDED, PROPERTY_CHANGED and PROPERTY_REMOVED. Multiple values, separated by a comma, can be inserted. By default, all types are monitored.	null
repository	Workspace in which the event is monitored.	null
path	Path from which the event is triggered.	null
includeSubNodes	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 true.	false
delay	Optional. Delay in milliseconds before the listener is triggered.	null
maxDelay	Optional. Maximum delay milliseconds before the listener is triggered.	null

Command and class properties and parameters

The following properties are specific to the command triggered in response to the event or the class executed.

Property	Description	Default Value
/listener/class	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).	null
/listerner/nodeType	Optional. Limits monitoring to a single node type. By default, all node types are monitored.	null
/listener/command/class	Fully qualified name of the command executed.	null
/listener/command/repository	Workspace in which the command is executed.	null
/listener/params/<parameter>	Optional. Parameters sent to the command as determined by the command class. Not all commands allow for parameters.	null

Commands

Out of the box, two classes are provided for use with commands:

1. RestrictToNodeTypeEventListener implements the restrict path to node type behavior class.
2. RegexEventListener filters 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/regex that specifies the pattern.

These classes can be used with any command that ships with Magnolia CMS and most custom commands. For more information about configuring a command, see Commands.

Classes

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 > /modules/observation/config/listenerConfigurations/activateAddedPages.

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.

Modify the activateAddedPages configuration as follows:

1. Copy the activateAddedPages node and name the copy activateDownloads.
2. Set active to true to enable the listener.
3. Set description to describe what the listener does.
4. Set path to /demo-project/downloads.
5. Set repository to dms.
6. Set nodeType to mgnl:contentNode.
7. Set /listener/command/repository to dms.

To test, upload a new file to dms:/demo-project/downloads. It will be activated automatically to the public instance.

The wiki article Autoactivation of user details describes a similar use case for automatically activating user accounts using the Observation module.