Magnolia 5.5 reached end of life on November 15, 2019. 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.
<dependency> <groupId>info.magnolia</groupId> <artifactId>magnolia-module-observation</artifactId> <version>2.0.5</version> </dependency>
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. 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 require additional properties that the command class supports.
The module includes a sample, self-contained listener,PageListener, that reacts to an event on its own. The reaction is hard-coded in the class and outputs the following message to the console when a page is added.
EventListener Test: Text Message EventListener Test: Text Message2
Example: Basic PageListener
configuration in /modules/observation/config/listenerConfigurations
.
Node name | Value |
---|---|
observation | |
config | |
listenerConfigurations | |
pageAddedAlert | |
listener | |
class | info.magnolia.module.observation.sample.PageListener |
nodeType | mgnl:page |
active | true |
delay | 31 |
description | Writes message to console when a page is added |
eventTypes | NODE_ADDED |
includeSubNodes | true |
maxDelay | 40 |
path | / |
repository | website |
Properties:
listenerConfigurations | required Listener configuration node. |
| required Arbitrary node name. |
| required Listener node. |
| required Fully-qualified listener class name. |
| optional, default is all node types Restricts observation to events on the specified node type, for example |
| required Path to the node that is observed. |
| required Workspace of the observed node. |
| optional, default is Enables and disables the listener. |
| optional Delay in milliseconds before the reaction is triggered. |
| optional Listener description. |
| optional, default is all event types Type of JCR event monitored. Options: |
| optional, default is Observe also events in subnodes. For example, only changes to the page would be observed by default. Set to |
| optional Maximum delay milliseconds before the reaction is triggered. |
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.
A command event listener delegates the reaction to a command. You can use an existing command or write your own.
The module installs two example command listener configurations in /modules/observation/config/listenercConfigurations/
:
activateAddedPages
: Uses ActivationCommand
to automatically activate new pages.sendMailOnPageChange
: Uses MailCommand
to send an email message when a page is created, updated or deleted. pageChangeNotification
mail template has been configured in the Mail module.Node name | Value |
---|---|
observation | |
config | |
listenerConfigurations | |
activateAddedPages | |
sendMailOnPageChanges | |
listener | |
command | |
class | info.magnolia.module.mail.commands.MailCommand |
params | |
model | |
class | info.magnolia.module.observation.model.PageChangeNotifModel |
mailTemplate | pageChangeNotification |
mailTo | user@your-company.com |
type | freemarker |
class | info.magnolia.module.observation.commands.RestrictToNodeTypeEventListener |
nodeType | mgnl:page |
active | true |
delay | 31 |
description | A mail will be sent when a page is created/updated/removed |
includeSubNodes | true |
maxDelay | 40 |
path | / |
repository | website |
Command-specific listener properties:
listenerConfigurations | required Listener configuration node. |
| required Arbitrary node name. |
| required Listener node. |
| required Command node. |
| required Fully-qualified command class name the reaction is delegated to. |
| optional Parameters passed to the command. For example the |
| required Fully-qualified name of the command listener class. |
| optional, default is all node types Restricts observation to events on the specified node type. |
| optional/requried Same as standard listener properties. |
Listeners may rely on the Mail module to send emails. Configure SMTP setting to ensure they work.
The module provides the following listener classes:
info.magnolia.module.observation.sample.PageListener | PageListener | Writes a message to the console when a page is added. |
info.magnolia.module.observation.commands.CommandEventListener | CommandEventListener | Executes a command when an event occurs. |
info.magnolia.module.observation.commands.RestrictToNodeTypeEventListener | RestrictToNodeTypeEventListener | Executes a command when an event occurs in the specified node type. |
info.magnolia.module.observation.commands.RestrictToTemplateEventListener | RestrictToTemplateEventListener | Executes a command only when an event occurs in the specified node that has a specified template type as a resource node. |
info.magnolia.module.observation.commands.RegexEventListener | RegexEventListener | Executes a command when an event occurs in the specified node type and matches a regular expression pattern. |
info.magnolia.module.observation.commands.SpecifiedNodeTypeOnlyEventListener | SpecifiedNodeTypeOnlyEventListener | 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. |
This example command listener configuration observes the NODE_ADDED
event in the dam
workspace. To test the listener, upload a new asset.
The
dam
workspace is defined twice. The property is always required under the listener configuration. In this case it is also required as a parameter by the ActivationCommand
.
Example: Automatically activate new assets added in the Assets app.
Node name | Value |
---|---|
listenerConfigurations | |
activateAssets | |
listener | |
command | |
class | info.magnolia.module.activation.commands.ActivationCommand |
params | |
repository | dam |
class | info.magnolia.module.observation.commands.RestrictToNodeTypeEventListener |
nodeType | mgnl:asset |
active | true |
description | Automatically activate new assets |
eventTypes | NODE_ADDED |
path | / |
repository | dam |