Skip to end of metadata
Go to start of metadata

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

Download the Observation module from our Nexus repository

Installing

Observation is a Community Edition module.

(warning) The Observation module is not installed by default. If you don't find a version node in Configuration > /modules/observation then the module is not installed.

Node nameValue

 modules

 

 observation

 

 config

 

 version

2.0.1

You can find listeners installed by other rmodules under the config node even if the Observation module is not installed.

 Click for installation steps...

(warning) Create a backup of your system before you install a module. Uninstalling a module is not as simple as removing the .jar file. Modules add and change configurations and may change the content. Try new modules in a test environment first. A module consists of a JAR file and may include dependent JAR files. Modules are responsible for updating their own content and configurations across versions. Be sure to keep only one version of each module and its dependencies.

To install a module:

  1. Stop the application server.
  2. Copy the module JAR files into the WEB-INF/lib directory. The location of this directory depends on the application server.
    • Tomcat: /webapps/magnoliaAuthor/WEB-INF/lib
    • JBoss: /server/default/deploy/magnoliaAuthor/WEB-INF/lib
  3. Restart the server.
  4. Go to the AdminCentral URL.
  5. Start the Web update process.
  6. Click Start up Magnolia.

Repeat the steps for each author and public instance.

Uninstalling

 Click for uninstallation steps...

To uninstall a module, remove the module JAR file from the /WEB-INF/lib folder and restart Magnolia CMS.

(warning) However, this is rarely enough. Modules add and modify configuration during installation. The use of a module also changes content. Removing all of these changes is difficult without knowing the installation tasks in detail. To test a module, use the embedded Derby database and take a backup of your repositories folder. Install the module and try it. When you are done testing, remove the module JAR and restore the repositories folder from the backup. This way you can go back to square one. We also recommend that you segregate the development and production environments. Take regular backups for disaster recovery so you can revert to a prior state in a routine fashion.

Event listeners

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.

Listener configuration

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 PageListener class.

Node nameValue

 modules

 

 observation

 

 listenerConfigurations

 

 pageAddedAlert

 

 listener

 

 class

info.magnolia.module.observation.sample.PageListener

 active

true

 delay

31

 description

Writes message to console when a page is added

 eventTypes

NODE_ADDED

 includeSubNodes

true

 maxDelay

40

 path

/demo-project

 repository

website

Here's what the output written to the console looks like:

Output in console

Listener properties:

  • <listener name>
    • 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:page for 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 false.
    • 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  NODE_ADDED, NODE_MOVEDNODE_REMOVED, PROPERTY_ADDED, PROPERTY_CHANGED, PROPERTY_REMOVED and 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 includeSubNodes to true.
    • 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.

Listener classes

Magnolia provides the following listener classes:

ClassDescription
info.magnolia.module.observation.sample.PageListenerWrites a message to the console when a page is added.
info.magnolia.module.observation.commands.CommandEventListenerExecutes a command when an event occurs.
info.magnolia.module.observation.commands.RestrictToNodeTypeEventListenerExecutes a command when an event occurs in the specified node type.
info.magnolia.module.observation.commands.RegexEventListenerExecutes a command when an event occurs in the specified node type and matches a regular expression pattern.
info.magnolia.module.observation.commands.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.

Command event listeners

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 the sendMailOnPageChanges listener. It observes changes to pages and delegates the reaction to the MailCommand which sends a notification.

Node nameValue

 modules

 

 observation

 

 listenerConfigurations

 

 sendMailOnPageChanges

 

 listener

 

 command

 

 class

info.magnolia.module.mail.commands.MailCommand

 params

 

 mailTemplate

pageChangeNotification

 mailTo

publisher@example.com

 type

freemarker

 class

info.magnolia.module.observation.commands.RestrictToNodeTypeEventListener 

 nodeType

mgnl:page

 active

true

 includeSubNodes

true

 path

/

 repository

website

Properties specific to command listeners:

  • <listener name>
    • command :
      • 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 MailCommand.
        • 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 RestrictToNodeTypeEventListener.

    • includes: Optional. Included list of node types that the SpecifiedNodeTypeOnlyEventListener observes.
      • <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 SpecifiedNodeTypeOnlyEventListener ignores.
      • <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.

Examples

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.

Activating assets automatically

The example below automatically activates any new asset added in the Assets app. The listener observes the NODE_ADDED event in the dam workspace. To test the listener, upload a new asset.

Node nameValue

 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

 includeSubNodes

true

 path

/

 repository

dam
Labels