Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.
The Observation module allows you to listen to events in the repository and trigger a reaction. Use observation to automate tasks such as publishing newly added assets or sending an email notification when a comment is added. Custom event listeners can react to almost any event. The Observation module is based on the JCR observation feature.
Download the Observation module from Magnolia Store or Nexus repository.
Observation is a Community Edition module.
The Observation module is not installed by default. To check whether it is installed, go to Magnolia Store > Installed modules in AdminCentral. If you don't find a version node in
/modules/observation then the module is not installed. You can find listeners installed by other modules under the
config node even if the Observation module is not installed.
To install the module, please see the general module installation instructions.
See the general module uninstalling instructions and advice.
An event listener registers an interest in a particular type of event. The job of the listener is to detect the event and possibly react to it.
Example: You want to send an email notification when a new page is added. Configure an event listener that listens to the NODE_ADDED event. This event occurs when a new node is added. Limit the listener to the
mgnl:page node type so you only get notified about pages, not other types of nodes. Finally, define the mail command as the desired reaction.
Magnolia provides two types of event listeners: listeners that react to the event on their own and listeners that delegate the reaction to a command. Both listeners are configured the same way but command event listeners have some extra properties.
Here is a basic
pageAddedAlert listener. It listens to the NODE_ADDED event and reacts by writing a message to the console when new content is added. This is an example of a self-contained listener that reacts to the event on its own. The reaction is hard-coded in the
Here's what the output written to the console looks like:
EventListener Test: Text Message EventListener Test: Text Message2
listener: Identifies the configuration as an event listener.
class: Fully-qualified listener class name.
nodeType: Optional. Restricts observation to events that occur in the specified node type, for example
mgnl:pagefor pages. Use together with a listener class that observes node type. By default all node types are monitored.
active: Enables and disables the listener. Default is
delay: Optional. Delay in milliseconds before the reaction is triggered.
description: Optional. Listener description.
eventTypes: Optional. The type of JCR event monitored. Possible types are
PERSIST. Separate multiple types with a comma. All types are monitored by default.
includeSubNodes: Optional. Observes also events in subnodes. Default is
false. For example, by default only changes to the page itself would be observed. If you also want to observe changes to components under the page node, set
maxDelay: Optional. Maximum delay milliseconds before the reaction is triggered.
path: Mandatory. Path to the node that is observed.
repository : Mandatory. Workspace in which the observed node resides.
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 contacts, for example, require one listener to monitor folders (
nodeType=mgnl:folder) and another to monitor files (
nodeType=mgnl:contact). 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.
Magnolia provides the following listener classes:
|Writes a message to the console when a page is added.|
|Executes a command when an event occurs.|
|Executes a command when an event occurs in the specified node type.|
|Executes a command when an event occurs in the specified node type and matches a regular expression pattern.|
Executes a command when an event occurs in a node that is in the "included" list of node types and not on the "excluded" list.
A command event listener delegates the reaction to a command. You can reuse any of Magnolia's existing commands or write your own.
Here's an example
sendMailOnPageChanges listener. It observes changes to pages and delegates the reaction to
MailCommand which sends a notification. This example assumes the
pageChangeNotification mail template has been configured in the Mail module.
Properties specific to command listeners:
class: Fully-qualified name of the command class the reaction is delegated to.
params: Optional. Parameters passed to the command. For example the
mailTemplateused to compose the mail body, required by the
repository : Workspace passed to the command. Some commands require this so you need to define it in two places: here as a parameter and under the listener configuration.
<other>: Any other configuration supported by the command. For example
nodeType in the case of
includes: Optional. Included list of node types that the
<node type name 1>: Node type to observe.
<node type name 2>: Node type to observe.
<node type name 3>: Node type to observe.
excludes: Optional. Excluded list of node types that the
<node type name 1>: Node type to ignore.
<node type name 2>: Node type to ignore.
<node type name 3>: Node type to ignore.
class: Fully-qualified name of the command listener class.
Listeners may rely on the Mail module to send emails. Configure SMTP setting to ensure that they work.
Magnolia provides the following example listeners:
sendMailOnPageChanges: Sends an email message when a page is created, updated or deleted.
sendMailOnPageComments: Installed by the Mail module to send an email when a user comments on a page.
activateAddedPages: Automatically activates new pages
versionResourcesOnChange: Automatically versions STK resources.
versionTemplatesOnChange: Installed by the In-place Templating module to automatically version STK templates.
generateCategories: Installed by Categorization module to automatically generate categories.
The example below automatically activates any new asset added in the DMS. The listener observes the
NODE_ADDED event in the
dms workspace. To test the listener, upload a new asset.