Respond to Publish Changes, Discard Changes, and Create Preview Configuration Channel Events

Overview

This page describes how to implement custom logic that responds to channel publish, discard, and preview configuration creation events in Bloomreach Content.

When to Use

Use channel event listeners when you need to validate or process actions triggered by users publishing or discarding channel changes, or when a preview configuration is created for a channel. This approach is relevant when your delivery tier requires additional logic during these operations.

Channel Events

Channel events are published to the synchronous HST internal event bus. You can subscribe to these events to execute custom logic or to interrupt the process if requirements are not met.

A ChannelEvent object is published to the event bus in the following scenarios:

1. When a user publishes changes in the Experience manager (ChannelEvent.ChannelEventType#PUBLISH)
2. When a user discards changes in the Experience manager (ChannelEvent.ChannelEventType#DISCARD)
3. When a preview configuration is created for a channel (ChannelEvent.ChannelEventType#PREVIEW_CREATION)

At the time the event is published, changes are not yet persisted.

Implementation

Responding to a ChannelEvent

To handle channel events, implement a listener class that subscribes to the event bus. The listener must:

• Check if an exception is already set on the event (ChannelEvent.getException())
• Verify the event type (ChannelEvent.getChannelEventType())

The following example demonstrates a listener implementation:

site/components/src/main/java/org/example/listeners/MyChannelEventListener.java

package org.example.listeners;

import org.hippoecm.hst.pagecomposer.jaxrs.api.ChannelEvent;
import org.hippoecm.hst.pagecomposer.jaxrs.api.ChannelEvent.ChannelEventType;
import org.hippoecm.hst.pagecomposer.jaxrs.api.ChannelEventListenerRegistry;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import org.onehippo.cms7.services.eventbus.Subscribe;

public class MyChannelEventListener {

    private static final Logger log = LoggerFactory.getLogger(MyChannelEventListener.class);

    @SuppressWarnings("UnusedDeclaration")
    public void init() {
        ChannelEventListenerRegistry.get().register(this);
    }

    @SuppressWarnings("UnusedDeclaration")
    public void destroy() {
        ChannelEventListenerRegistry.get().unregister(this);
    }

    @Subscribe
    public void onEvent(ChannelEvent event) {
        if (event.getException() != null) {
            return;
        }

        final ChannelEventType type = event.getChannelEventType();
        if (type != ChannelEventType.DISCARD && type != ChannelEventType.PUBLISH) {
            log.debug("Skipping ChannelEvent '{}' because type is not equal to {} or {}.", type,
                    ChannelEventType.PUBLISH, ChannelEventType.DISCARD);
            return;
        }

        log.info("Channel: {}, event: {}, user: {}", event.getEditingPreviewSite().getName(),
                event.getChannelEventType(), event.getUserIds());

    }

}
copy

Register the listener as a Spring bean:

site/components/src/main/resources/META-INF/hst-assembly/overrides/channel-event-listeners.xml

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">

  <bean class="org.example.listeners.MyChannelEventListener" init-method="init" destroy-method="destroy"/>
  
</beans>
copy

Aborting a Channel Action

To abort the action that triggered a channel event, set an exception on the event object. This is appropriate if a requirement is not met or post-processing fails. For more information, see Abort an Experience Manager Action.

Handling Channel Events in a Project Context

If you use the Projects feature, channel events may occur in different contexts. For example, a publish event may indicate either that changes are live or that changes are submitted within a project and will not go live until the project is merged.

To determine the context of a ChannelEvent, check whether the event is for the channel core or for a channel branch within a project:

event.getEditingPreviewSite().getChannel().getBranchOf();
copy

• If the event is for the channel core, getBranchOf() returns null.
• If the event is for a channel branch in a project, getBranchOf() returns the ID of the branched channel.