Namespace actions

Actions are the mechanism through which notifications send messages back to the application that created them. The service defines a number of ways in which actions can be raised (a notification being interacted with by the user, being closed, expiring, etc.), and it is up to each application to decide if it wishes to be informed when each of these triggers occur.

For an action to be raised when one of these triggers occurs, the application must specify an action result for each trigger it is interested in. The application should then listen for when these actions are raised by listening for the notification-action event.

This event is fired once each time an action is raised, and will contain the action result the application specified for that trigger. The application may then use the action result to determine which trigger occurred and respond appropriately.

If an action result is not specified for a particular trigger, or it is set to null, the application will not receive a corresponding notification-action when that trigger occurs.

Unlike other event types, notification-action events will be buffered by the service until the application has added a listener for this event type, at which point it will receive all buffered notification-action events. The service will also attempt to restart the application if it is not running when the event is fired.

For an overview of actions, consider the sample notification below:

import {addEventListener, create} from 'openfin-notifications';

// Create a notification with two buttons
create({
    // Basic info
    title: 'Reminder',
    body: 'Event "Weekly Meeting" is starting soon...',

    // We'll use the 'customData' field to store metadata about the event
    customData: {eventId: '12345'},

    // We want the user clicking the notification to open the associated event, so register an 'onSelect' action
    onSelect: {task: 'view-calendar-event', target: 'popup'},

    buttons: [
        // A button that will schedule another reminder for 5 minutes from now. Since the application will be
        // responsible for snoozing the event, it will need to know about the user clicking this button. By setting
        // a NotificationActionResult for 'onClick', the service will raise a "notification-action" event when this
        // button is clicked, and will pass the value of 'onClick' as the 'result' field within the event
        {
            title: 'Snooze for 5 minutes',
            iconUrl: 'https://www.example.com/timer.png',
            onClick: {
                task: 'schedule-reminder',
                intervalMs: 5 * 60 * 1000
            }
        },

        // A button that closes the notification and doesn't prompt the user about this event again. Since the
        // application doesn't need to do anything when the user clicks this button, we leave 'onClick' undefined
        // rather than specifying a NotificationActionResult. This means that no action will be raised when the
        // button is clicked, and hence no "notification-action" event will be fired
        {
            title: 'Dismiss',
            iconUrl: 'https://www.example.com/cancel.png'
        }
    ]
});

// Create a listener that will be called for each action
// Note: This handler will be used for ALL actions, from ALL notifications that are created by this application.
addEventListener('notification-action', (event: NotificationActionEvent) => {
    const {result, notification} = event;

    if (result['task'] === 'view-calendar-event') {
        // Open a window with full details of the associated event
        openEventDetails(notification.customData.eventId, result['target']);
    } else if (result['task'] === 'schedule-reminder') {
        // Schedule a new notification
        scheduleReminder(notification.customData.eventId, Date.now() + result['intervalMs']);
    } // Etc...
});

The example above uses customData to store details about the notification subject (in this case, a calendar event), and onClick actions to inform the application about how it should respond when the user interacts with the notification. This is our intended usage and recommended best-practice, but the service doesn't require applications to follow this convention - application developers are free to decide how to manage notification state.

Within the notification-action handler, the application must be able to understand which notification is being handled, and how to decide what it should do next. The example above uses an application-defined action field to determine the correct action, but the notification's id, customData and other fields are also useful selectors.