Customizing notification actions

An action is something that can be used to interact with notifications from within the context of where the notification was received. While Brightspot already provides users with some action options without any additional development, the following APIs can be leveraged in order to further customize what actions can be available for specific notifications. These implementations are not specific to the context of the CMS, as other delivery methods, such as Slack and email, will also leverage the same code.

Action

The Action class represents the actual behavior that will execute when a user interacts with a notification. Create an implementation of Action<D extends ActionInput>, where ActionInput is the form that appears when a user clicks an action and contains any additional action input data. (If no form appears and no data needs to be passed with the action, then the ActionInput implementation can simply be empty — see WatcherActionInput).

public abstract class Action<D extends ActionInput> extends Record {

    public int getPosition() {
        return 0;
    }

    public String getSubmitLabel() {
        return ToolLocalization.text(this, "label.submit", "Execute");
    }

    public abstract ActionResult execute(D actionInput) throws ActionExecutionException;
}

ActionInput is the form that appears when a user clicks an action. The form contains additional action input data as necessary. (If no form appears and no data needs to be passed with the action, then the ActionInput implementation can be empty.)
Override this method to customize the position the action in the list of actions.
Gets the call to action label for the action. Overriding the action class's localization value for label.submit will change the submit button's label.
This implementation determines what happens when the user clicks the submit button and what the result is.

Usage Example

public class WorkflowAction extends Action<WorkflowActionInput> {

    private WorkflowLog workflowLog;

    // Constructors ommitted

    // Getters & Setters ommitted

    @Override
    public ActionResult execute(WorkflowActionInput actionInput) throws ActionExecutionException {
        transitionWorkflow(actionInput);

        return ActionResult.newSuccess(ToolLocalization.text(this, "message.success",
            "Workflow Transition Successful!"));
    }
    
    private void transitionWorkflow(WorkflowActionInput input) {
        // Transition content here...
    }
}

public class WorkflowActionInput extends ActionInput {

    @ToolUi.ValueGeneratorClass(WorkflowNameValueGenerator.class)
    @Recordable.Required
    private String transition;

    private String comment;
    
    // Getters & Setters ommitted
}

Given the WorkflowActionInput and workflowLog, transition the asset to the correct status.
Return a successful result if the execution was successful, otherwise throw an exception or handle appropriately.

Action Provider

The ActionProvider interface determines which actions should be included in the action bar for a specific notification type.

public interface ActionProvider {

    <T extends Topic<P>, P extends Recordable> List<Action<?>> getActions(MessageContext<T, P> messageContext);

}

Given the messageContext, return the actions that should display in the action bar.

Usage Example

public class WorkflowActionProvider implements ActionProvider {

    @Override
    public <T extends Topic<P>, P extends Recordable> List<Action<?>> getActions(MessageContext<T, P> messageContext) {

        P payload = messageContext.getPayload();

        if (payload instanceof WorkflowLog) {
            WorkflowLog workflowLog = (WorkflowLog) payload;
            return List.of(new WorkflowAction((WorkflowLog) payload));
        }

        return List.of();
    }
}

The payload contains the information relevant to the current notification.
Only show the action if the notification's payload is a WorkflowLog, indicating that this is a Workflow-specific notification.
If the current notification should include this workflow action, then return an empty list of actions.

Additional APIs

The ActionResult class represents the result of executing an action. This class contains a message string, which can be used to describe the action's success, and a resultUrl string if the action will result in a callback URL.
The ActionExecutionException class represents an expected error that occurs as the result of Action#execute executing an action. Throwing an ActionExecutionException when error handling helps to properly display errors to the user.

Previous Topic

Enabling and configuring actionable notifications

Next Topic

Tutorial: Configuring a user to receive content report notifications