Skip to end of metadata
Go to start of metadata

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

The Observation module is bundled with Magnolia CMS and typically not installed. You can download it from our Nexus repository

Installing

The Observation module is not installed by default, but other modules bootstrap configurations to the Configuration > /modules/observation/config/listenerConfigurations node. If you do not see a /observation/version node the module is not installed. Before installing the module export the versionTemplatesOnChange, sendMailOnPageComments and generateCategories listener configurations for later use. These are useful and will be overridden on installation of the module.

Observation is a Community Edition module. It is typically not installed. Launch the Configuration app and go to /modules/observation/version to check.

 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.

Configuration

Event listeners are configured at Configuration > /modules/observation/config/listenerConfigurations.

Listener types

Two types of event listeners are supported:

  1. Listeners that use their own event listener class.
  2. Listeners that execute command when an event occurs.

The configuration of the two listener types is very similar.

On installation three example listeners that all execute commands are registered are registered:

  • sendMailOnPageChanges: Sends a mail when a page is created, updated or deleted.
  • activateAddedPages: Automatically activates new pages
  • versionResourcesOnChange: Automatically versions STK resources.

Other available examples:

  • versionTemplatesOnChange: Installed by the In-place Templating module to automatically version STK templates.
  • sendMailOnPageComments: Installed by the Mail module to send an email when a user comments on a page.
  • generateCategories: Installed by Categorization module to automatically generate categories.

(warning) If you did not export these configurations prior to installation of the Observation module you can export them from our online demo site.

Simple listener configuration

All listeners follow this configuration structure and use the same properties. Command listeners have additional nodes and options. Here's an example configuration that triggers the sample PageListener that prints a message to the console.

  • <listener name>: Arbitrary name.
    • listener: Identifies the configuration as an event listener.
      • class: Fully qualified listener class name.
    • active: Optional. Enables and disables the listener. Default is false.
    • delay: Optional. Delay in milliseconds before the listener is triggered.
    • description: Listener description.
    • eventTypes: Optional. The type of JCR event monitored. Possible values:  NODE_ADDED, NODE_MOVEDNODE_REMOVED, PROPERTY_ADDED, PROPERTY_CHANGED, PROPERTY_REMOVED and PERSIST. Multiple values separated by a comma can be used. By default all types are monitored.
    • includeSubNodes: Optional. Monitors subnodes when set to true. Default is false.
    • maxDelay: Optional. Maximum delay milliseconds before the listener is triggered.
    • nodeType: Optional. To restrict restrict the listener to a specific node type. By default all node types are monitored.
    • path: Required. Path from which the event is triggered.
    • repository: Required. Workspace in which the event is monitored.

      Node nameValue

       modules

       

       observation

       

       listenerConfigurations

       

       pageAddedAlert

       

       listener

       

      TEST   class

      info.magnolia.module.observation.sample.PageListener

      TEST   active

      true

      TEST   delay

      31

      TEST   description

      Writes message to console when a page is added

      TEST   eventTypes

      NODE_ADDED

      TEST   includeSubNodes

      true

      TEST   maxDelay

      40

      TEST   path

      /demo-project

      TEST   repository

      website

When you add a new page to /demo-project in the Pages app, an alert is written to the console.

Command listener configuration

Three event listener classes are provided for use with commands:

  1. RestrictToNodeTypeEventListener: Implements the restrict path to node type behavior. The sendMailOnPageComments configuration uses this listener class.
  2. SpecifiedNodeTypeOnlyEventListener: Reacts only if node type of the event (for node added/removed events) or parent node type (for property added/changed/removed events) is in the list of included node types and not in list of excluded node types. The versionTemplatesOnChange and versionResourcesOnChange configurations use this listener class.
  3. RegexEventListener filters events based on the node type and a regular expression pattern. Only events where the path matches the regex pattern are processed and execute the specified command. The configuration supports an additional  property, /listener/regex, to set the pattern.

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

Command listener configurations use the same basic configuration structure and properties as simple event listeners, with the addition of a command node and any other nodes supported by the command class. Here's the configuration of the sendMailOnPageComments listener:

  • <listener name>/listener
    • command:
      • class: Fully qualified class name of the command.
      • params: Parameters passed to the command.
      • <other>: Configuration nodes and properties supported by the command. For example content node includes in the case of SpecifiedNodeTypeOnlyEventListener.
    • class: Fully qualified name of the command listener class.
    • <other>: Properties supported by the command listener class. For example nodeType in the case of RestrictToNodeTypeEventListener.

      Node nameValue

       listenerConfigurations

       

       sendMailOnPageChanges

       

       listener

       

       command

       

      TEST   class

      info.magnolia.module.mail.commands.MailCommand

      TEST   repository

      website

       params

       

      TEST   from

      fromEmail@your-company.com

      TEST   mailTo

      toEmail@your-company.com

      TEST   subject

      event

      TEST   text

      page modified

      TEST   type

      text

      TEST   class

      info.magnolia.module.observation.commands.RestrictToNodeTypeEventListener 

      TEST   nodeType

      mgnl:page

      TEST   active

      false

      TEST   delay

       31

      TEST   description

      A mail will be sent when a page gets created/updated/removed

      TEST   eventTypes

       

      TEST   maxDelay

       40

      TEST   path

      /

      TEST   repository

      website

Automatically activate assets

The example configuration below automatically activates assets added in the Assets app.  It listens to the NODE_ADDED event in the dam workspace.

Node nameValue

 listenerConfigurations

 

 activateAssets

 

 listener

 

 command

 

TEST   class

info.magnolia.module.activation.commands.ActivationCommand

TEST   repository

dam

TEST   class

info.magnolia.module.observation.commands.RestrictToNodeTypeEventListener 

TEST   nodeType

mgnl:asset

TEST   active

true

TEST   description

Automatically activate assets

TEST   eventTypes

NODE_ADDED

TEST   includeSubNodes

true

TEST   path

/

TEST   repository

dam

To test, upload a new file to in the Assets app. It will be activated automatically to the public instance.

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.

Labels