Abort an Experience Manager Action

Overview

This page explains how to abort an Experience Manager action using a channel event listener. You can control whether the Experience Manager UI displays a generic or custom error message by choosing the appropriate exception type.

When to Abort an Action

Abort an Experience Manager action when a required condition is not met or post-processing fails during a channel event. Use the event listener mechanism to stop the action and provide feedback to the user.

Exception Types

Channel event listeners that use the HST internal event bus can abort actions by setting an exception on the event object. There are two supported exception types:

RuntimeException: Triggers a generic error message in the Experience Manager UI. The message is also logged on the server.
ClientException: Allows you to provide a custom feedback message for the Experience Manager UI.

For details on event listeners, see Overview of Channel Manager Events and Response Mechanisms.

Abort with a Generic Error Message (RuntimeException)

To abort an action and display a generic error message, set a RuntimeException on the event object in your event listener:

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

    event.setException(new RuntimeException("This will abort the action"));        
}

Behavior:

The Experience Manager UI displays a generic message such as Failed to publish changes.
The server log records the exception message and stack trace. Example log entry:

08.04.2019 11:09:26 WARN  http-nio-8080-exec-3 [AbstractConfigResource.logAndReturnServerError:184] java.lang.RuntimeException: This will abort the action

Abort with a Custom Feedback Message (ClientException)

To provide a custom error message in the Experience Manager UI, set a ClientException with a user message:

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

    final Map<String, String> parameterMap = new HashMap<>();
    parameterMap.put("userMessage", "Channel {{channel}} can't be published after 9 PM");
    parameterMap.put("channel", event.getEditingPreviewSite().getName());
    final String techDetails = "add technical details here"; 
    event.setException(new ClientException(techDetails, ClientError.UNKNOWN, parameterMap));        
}

Behavior:

The Experience Manager UI displays the userMessage value as feedback to the user.

Limitations:

The custom message cannot be localized because the event listener does not have access to the authenticated user's locale. This limitation may be addressed in a future release. For updates, see the relevant JIRA ticket.

Summary

Use RuntimeException to abort an action with a generic error message.
Use ClientException to abort an action and provide a custom feedback message in the UI.
Both approaches prevent the Experience Manager action from completing.

Choose the exception type based on the feedback you want to provide to the user.