Notifications

Notifications represent events important enough to be brought to the attention of the user. Some examples are:

• an alert from an app for an automatic machine restart, or from a metrics monitoring tool for a system running hot;
• a trade order execution notification from an Order Management System;
• a workflow task assigned to a user or a group of users that can optionally need a response - e.g., a change of client address;
• an activity that is forwarded or re-assigned to a user - e.g., handling a client call;

io.Connect Desktop provides a notification service that normalizes and consolidates notifications from different apps and delivers them directly to the user on the desktop in a customizable UI as both toasts and ordered lists in a Notification Panel.

The notification toasts and the Notification Panel are configurable and completely customizable system apps.

Interop-enabled apps can use the io.Connect Notification APIs to raise notifications dynamically.

io.Connect Desktop shows notifications on the desktop using notification toasts and a Notification Panel:

Notification Toasts

Notifications can be shown on the desktop as notification toasts. You can close them manually, snooze them, or interact directly with them by clicking on the notification or on an action button in it. Toasts expire based on configuration and hide automatically after the specified time has elapsed:

Notification toasts can be configured from the Notification Settings panel to group automatically in stacks by app or by severity. This improves the user experience and saves space on the screen. When you click on a notification stack, it expands and displays all notification toasts in it. You can then interact with the notifications in it, clear the entire stack, or collapse it by clicking on a notification in it:

Notification Panel

The Notification Panel is accessible via the io.Connect launcher and contains all received notifications that haven't been closed or acknowledged by the user. Notifications in it can be sorted by date, severity, snoozed status, read or unread status. You can close notifications individually. snooze them, or interact with them by clicking on the notification or on an action button in it. You can use the "Clear All" button to clear all notifications from the Notification Panel:

Notification Settings

The Notification Panel has a "Settings" button that opens a panel with notification settings. You can use it to enable or disable notifications globally or per app and provide various settings for the Notification Panel and the notification toasts:

After selecting the desired settings, close the Notification Settings panel and your changes will be saved automatically.

Snoozing Notifications

Available since io.Connect Desktop 9.3

Notifications can be snoozed from the UI and programmatically. Snoozed notifications will be shown to the user again as notification toasts after the specified snooze duration has elapsed. To snooze a notification manually, hover over a notification toast or a notification inside the Notification Panel and click the "Snooze" button that appears on hover. You can set the snooze duration from the Notification Settings panel:

Notification Badges

Notification badges will appear on the io.Connect Desktop icon in the Windows taskbar (or the Dock on macOS) and the system tray icon when there are pending notifications, so that the user won't miss them. The badge on the taskbar icon shows the number of notifications that the user hasn't seen yet, while the system tray icon badge simply alerts the user that there is at least one new notification:

By default, notifications are enabled in io.Connect Desktop. To specify global notification settings, use the "notifications" top-level key in the system.json system configuration file of io.Connect Desktop.

The "notifications" object has the following properties:

The "snooze" object has the following properties:

The "placement" object has the following properties:

The "sourceFilter" object has the following properties:

The "toasts" object has the following properties:

The following is an example configuration for notifications:

{
    "notifications": {
        "enabled": true,
        "enableToasts": true,
        "sourceFilter": {
            "allowed": ["*"]
        },
        "toastExpiry": 15000
    }
}

io.Connect Desktop shows notifications by using two system apps - an app that shows the notification toasts and an app that shows the Notification Panel. Both apps are built with the components provided by the IONotifications object of the @interopio/components-react library. You can use the same components to create custom notification apps and replace either or both of the default apps.

To create custom notification apps:

1. Implement the apps with the <Toasts /> and <Panel /> components.
2. Configure the apps as notification apps of io.Connect Desktop.
3. Customize the app styles.

The <Toasts /> and <Panel /> components render fully functional notification toasts and Notification Panel without the need for any additional configuration. Use their components prop to replace the default components that they render. Use the hooks exported by IONotifications to read and change the notifications and the notification settings from your own components.

Setup

Render the notification apps within the <IOConnectProvider /> component of the @interopio/react-hooks library. Initialize the @interopio/desktop library with the apps property set to true to enable the Apps API, which the notification components use for retrieving and starting apps.

The notification apps depend on a set of React context providers from @interopio/components-react. They supply the theme, notifications, notification settings, and Notification Panel state that the notification apps require to operate properly. If a provider is missing, the functionality that depends on it won't work. You must render the <Toasts /> and <Panel /> components within all of them, in the order demonstrated in the following examples.

You must also import the CSS files for the notifications and for the UI components that they use.

The following example demonstrates how to render the default Notification Panel app:

import { IOConnectProvider } from "@interopio/react-hooks";
import IODesktop from "@interopio/desktop";
import { ThemeProvider, IONotifications } from "@interopio/components-react";
import "@interopio/theme";
import "@interopio/components-react/dist/styles/components/ui/dropdown-menu.css";
import "@interopio/components-react/dist/styles/components/ui/overlay-scrollbars-container.css";
import "@interopio/components-react/dist/styles/features/notifications/styles.css";

const {
    NotificationsProvider,
    NotificationsPanelProvider,
    Panel,
    useNotificationsContext,
    useShowHidePanelWindow,
    useHidePanelOnKeyUp,
    useHidePanelOnFocusLost
} = IONotifications;

const settings = {
    desktop: {
        factory: IODesktop,
        config: {
            apps: true
        }
    }
};

const NotificationPanel = () => {
    const { settings: { autoHidePanel } } = useNotificationsContext();

    useShowHidePanelWindow();
    useHidePanelOnKeyUp();
    useHidePanelOnFocusLost(autoHidePanel);

    return <Panel />;
};

const App = () => {
    return (
        <IOConnectProvider settings={settings}>
            <ThemeProvider>
                <NotificationsProvider>
                    <NotificationsPanelProvider>
                        <NotificationPanel />
                    </NotificationsPanelProvider>
                </NotificationsProvider>
            </ThemeProvider>
        </IOConnectProvider>
    );
};

export default App;

The Notification Panel app must show and hide its own window when the user opens or closes the Notification Panel. The hooks used in the example handle this.

The following example demonstrates how to render the default notification toasts app. The app will show its window only while there are active notifications, and will start the Notification Panel app when the user opens the Notification Panel:

import { useContext, useEffect } from "react";
import { IOConnectProvider, IOConnectContext } from "@interopio/react-hooks";
import IODesktop from "@interopio/desktop";
import {
    ThemeProvider,
    IONotifications,
    useShowHideWindow
} from "@interopio/components-react";
import "@interopio/theme";
import "@interopio/components-react/dist/styles/components/ui/dropdown-menu.css";
import "@interopio/components-react/dist/styles/components/ui/overlay-scrollbars-container.css";
import "@interopio/components-react/dist/styles/features/notifications/styles.css";

const {
    NotificationsProvider,
    NotificationsPanelProvider,
    Toasts,
    useNotificationsContext,
    useNotificationsPanelContext
} = IONotifications;

const settings = {
    desktop: {
        factory: IODesktop,
        config: {
            apps: true
        }
    }
};

const PANEL_APP_NAME = "io-connect-notifications-panel-application";

const NotificationToasts = () => {
    const io = useContext(IOConnectContext);
    const { notifications, settings: { enabledToasts } } = useNotificationsContext();
    const { isPanelVisible } = useNotificationsPanelContext();
    const hasActiveNotifications = notifications.some(notification => notification.state === "Active");

    // Show the window without focusing it.
    useShowHideWindow(hasActiveNotifications, false);

    useEffect(() => {
        if (!isPanelVisible) {
            return;
        }

        const startPanelApp = async () => {
            const panelApp = await io.apps.registry.get({ name: PANEL_APP_NAME });

            if (!panelApp || panelApp.instances.length > 0) {
                return;
            }

            await io.apps.instances.start({ name: PANEL_APP_NAME });
        };

        startPanelApp().catch(console.error);
    }, [io, isPanelVisible]);

    if (!enabledToasts || isPanelVisible) {
        return null;
    }

    return <Toasts />;
};

const App = () => {
    return (
        <IOConnectProvider settings={settings}>
            <ThemeProvider>
                <NotificationsProvider>
                    <NotificationsPanelProvider>
                        <NotificationToasts />
                    </NotificationsPanelProvider>
                </NotificationsProvider>
            </ThemeProvider>
        </IOConnectProvider>
    );
};

export default App;

Notification Panel

The <Panel /> component renders the Notification Panel. It has the following props:

The components object has the following properties:

If you don't set a property, the Notification Panel will render the default component for it. To remove a component, set its property to a component that returns null. The default <Header />, <HeaderCaptionTitle />, and <Body /> components are exported by IONotifications as <PanelHeader />, <PanelHeaderCaptionTitle />, and <PanelBody />, so you can combine them with your own components.

The following example demonstrates creating a Notification Panel with a custom title and without the search field:

import { IONotifications } from "@interopio/components-react";

const { Panel } = IONotifications;

const HeaderSearch = () => null;

// Define the components outside the render function to prevent unnecessary re-mounting.
const components = { HeaderSearch };

const MyPanel = () => <Panel title="Messages" components={components} />;

The Notification Panel app must also handle the visibility of its window. Use the following hooks in the component that renders the <Panel /> component:

Notification Toasts

The <Toasts /> component renders the notification toasts. It has the following props:

The components object has the following properties:

The following example demonstrates creating notification toasts that show up to three notifications at a time and have a custom header:

import { IONotifications } from "@interopio/components-react";

const { Toasts } = IONotifications;

const Header = () => <div>Latest Notifications</div>;

// Define the components outside the render function to prevent unnecessary re-mounting.
const components = { Header };

const MyToasts = () => <Toasts maxToasts={3} components={components} />;

Notifications

The <Notification /> component renders a single notification in the Notification Panel and in the notification toasts. It has the following props:

The components object has the following properties:

The <Header /> component and all components in it receive the notification in their notification prop. All default components are exported by IONotifications with the Notification prefix (e.g., <NotificationHeaderTitle />, <NotificationBodyIcon />), so you can combine them with your own components.

To use a custom notification, pass it as the Notification property of the components prop of the <Panel /> or the <Toasts /> component. The following example demonstrates creating a notification in the Notification Panel whose header title changes its color depending on the notification severity:

import { IONotifications } from "@interopio/components-react";

const { Panel, Notification } = IONotifications;

const severityColors = {
    Low: "#0066c0",
    Medium: "#43a047",
    High: "#f9a825",
    Critical: "#ff511f"
};

const HeaderTitle = ({ notification }) => {
    return <div style={{ color: severityColors[notification.severity] }}>{notification.appTitle}</div>;
};

// Define the components outside the render function to prevent unnecessary re-mounting.
const notificationComponents = { HeaderTitle };

const CustomNotification = (props) => <Notification {...props} components={notificationComponents} />;

const components = { Notification: CustomNotification };

const MyPanel = () => <Panel components={components} />;

Notification Settings

The "Settings" button in the Notification Panel opens the Notification Settings panel. To replace components in it, use the settings prop of the <Panel /> component. The settings object has the following properties:

Each component that a section renders is also a property of the settings object. All default components are exported by IONotifications with the Settings prefix (e.g., <SettingsGeneral />, <SettingsPlacementPanel />), so you can combine them with your own components.

The following example demonstrates creating a Notification Panel whose Notification Settings panel doesn't show the placement settings:

import { IONotifications } from "@interopio/components-react";

const { Panel } = IONotifications;

const Placement = () => null;

// Define the components outside the render function to prevent unnecessary re-mounting.
const settings = { Placement };

const MyPanel = () => <Panel settings={settings} />;

Notifications State

The IONotifications object exports hooks for reading and changing the notifications, the notification settings, and the state of the Notification Panel. Use them in components that you render within the notification providers.

The useNotificationsContext() hook returns an object with the following properties:

Each object in the allApps array has the following properties:

Each object in the notificationStacks array has the following properties:

The useNotificationsPanelContext() hook returns an object with the following properties:

Configuration

The default notification apps are defined in the notifications.json app definition file located in the <installation_location>/config/apps folder. The file contains the following app definitions:

To use a custom notification app, set the "url" property of the "details" top-level key in the respective app definition to the URL of your app. Keep the app name and the other properties of the app definition, so that the app window remains hidden, frameless, and on top of other windows:

{
    "name": "io-connect-notifications-panel-application",
    "details": {
        "url": "https://my-notification-panel.com"
    }
}

The notification toasts app starts the Notification Panel app by its name. The default notification toasts app expects the Notification Panel app to be named "io-connect-notifications-panel-application". To use another name, set the "panelApplicationName" property of the "customProperties" top-level key in the app definition of the notification toasts app:

{
    "name": "io-connect-notifications-application",
    "customProperties": {
        "panelApplicationName": "my-notification-panel"
    }
}

By default, the <Panel /> and <Toasts /> components set the size and the position of their windows based on the placement settings for notifications. To set the position of the window from the app definition instead, set the autoPlacement prop of the component to false and use the "placement" property of the "details" top-level key. The following example places the Notification Panel on the left of the screen:

{
    "details": {
        "placement": {
            "snapped": true,
            "horizontalAlignment": "left",
            "verticalAlignment": "stretch",
            "width": 350
        }
    }
}

ℹ️ For more details on io.Connect Window placement, see the Developers > Configuration > Application > Placement section.

Available since io.Connect Desktop 9.10 & @interopio/components-react 0.8

To customize the styles of the notifications, the Notification Panel, the notification toasts, and the Notification Settings panel, use the CSS variables provided by the io.Connect themes.