Observation module

Operations Bundled: Community Edition

Edition

CE

License

MLA, GPL

Issues

MGNLOBS

Maven site

Observation

Latest

2.2

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.

Installing with Maven

Bundled modules are automatically installed for you.

If the module is unbundled, add the following to your bundle including your project’s <dependencyManagement> section and your webapp’s <dependencies> section. If the module is unbundled but the version is managed by the parent POM, add the following to your webapp’s <dependencies> section.

<dependency>
  <groupId>info.magnolia</groupId>
  <artifactId>magnolia-module-observation</artifactId>
  <version>2.2</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>.

What is an event listener?

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.

Listener configuration

The module includes a sample, self-contained listener and info.magnolia.module.observation.sample.PageListener, which 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.

Console output
EventListener Test: Text Message
EventListener Test: Text Message2
Basic PageListener configuration in /modules/observation/config/listenerConfigurations
observation:
  config:
    listenerConfigurations:
      listener:
        class: info.magnolia.module.observation.sample.PageListener
      nodeType: mgnl:page (1)
      active: true
      delay: 31
      description: Writes messages to console when a page is added.
      eventTypes: NODE_ADDED
      includeSubNodes: true
      maxDelay: 40
      path: /
      repository: website
1 The nodeType parameter filters by matching the parent node type. For more see here.
Table 1. Parameter descriptions
Property Description

listenerConfigurations

required

Listener configuration node.

     <listener name>

required

Arbitrary node name.

         listener

required

Listener node.

             class

required

Fully qualified listener class name.

         nodeType

optional, default is all node types

Restricts observation to events on the specified node type, for example mgnl:page.

Only events whose associated parent node is of one of the node types in the nodeType String array will be received.
You can use it together with certain Listener classes that observe the specified node type.

         path

required

Path to the node that is observed.

         repository

required

Workspace of the observed node.

         active

optional, default is false.

Enables and disables the listener.

         delay

optional

Minimum delay (in milliseconds) before the reaction is triggered.

The delay and maxDelay properties form a range, and both values must be supplied to activate the feature.

         description

optional

Listener description.

         eventTypes

optional, default is all event types

Type of JCR event monitored.

Options

  • NODE_ADDED

  • NODE_MOVED

  • NODE_REMOVED,

  • PROPERTY_ADDED

  • PROPERTY_CHANGED

  • PROPERTY_REMOVED

  • PERSIST

Separate multiple types with a comma.

         includeSubNodes

optional, default is false

Observe also events in subnodes. For example, only changes to the page would be observed by default. Set to true, if you also want to observe changes to components under the page node.

         maxDelay

optional

Maximum delay (in milliseconds) before the reaction is triggered.

The delay and maxDelay properties form a range, and both values must be supplied to activate the feature.

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 contacts (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.

Command listener configuration

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 PublicationCommand to automatically publish new pages.

  • sendMailOnPageChange: Uses MailCommand to send an email message when a page is created, updated or deleted. WARNING: This example assumes the pageChangeNotification mail template has been configured in the Mail module.

Command listener configuration

Property Description

listenerConfigurations

required

Listener configuration node.

     <listener name>

required

Arbitrary node name.

         listener

required

Listener node.

             command

required

Command node.

                 class

required

Fully qualified command class name the reaction is delegated to.

             params

optional

Parameters passed to the command. For example the MailTemplate used to compose the mail body is required by MailCommand.

             class

required

Fully qualified name of the command listener class.

         nodeType

optional, default is all node types

Restricts observation to events on the specified node type.

         <listener properties>

optional/requried

Same as standard listener properties.

Listeners may rely on the Mail module to send emails. Configure SMTP setting to ensure they work.

Listener classes

The module provides the following listener classes:

info.magnolia.module.observation.sample.PageListener

Writes a message to the console when a page is added.

info.magnolia.module.observation.commands.CommandEventListener

Executes a command when an event occurs.

info.magnolia.module.observation.commands.RestrictToNodeTypeEventListener

Executes a command when an event occurs in the specified node type.

info.magnolia.module.observation.commands.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

Executes 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.

Activating assets automatically

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 PublicationCommand.

Example 1: Activating assets automatically

Automatically publish new assets added in the Magnolia Assets subapp.

📁 observation

     📁 config

         📁 listenerConfigurations

             ⸬ autoActivateAssets

                 ⸬ listener

                     ⸬ command

                         ⬩ class

info.magnolia.publishing.command.PublicationCommand

                     ⸬ 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

In this example, only Magnolia assets are published automatically.


Example 2: Activating folders and assets automatically

Automatically publish new folders and assets added in the Magnolia Assets subapp. In this second example, SpecifiedNodeTypeOnlyEventListener is used because it allows folders to be automatically published as well.

📁 observation

     📁 config

         📁 listenerConfigurations

             ⸬ autoActivateAssets

                 ⸬ listener

                     ⸬ command

                         ⬩ class

info.magnolia.publishing.command.PublicationCommand

                     ⸬ params

                         ⬩ repository

dam

                     ⸬ includes

                         ⬩ 0

mgnl:asset

                         ⬩ 1

mgnl:folder

                     ⬩ class

info.magnolia.module.observation.commands.SpecifiedNodeTypeOnlyEventListener

                 ⬩ active

true

                 ⬩ description

Automatically activate new assets & folders

                 ⬩ eventTypes

NODE_ADDED

                 ⬩ includeSubNodes

true

                 ⬩ path

/

                 ⬩ repository

dam

The SpecifiedNodeTypeOnly listener allows you to publish folders automatically. Included types to be published automatically are defined under the includes node.

If you upload assets in a zipped archive, publish the parent folder before uploading it. Otherwise, the assets won’t be automatically published.
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules