Customizing Desktop Assistant notifications using API parameters

  • Release version: Australia
  • Updated April 28, 2026
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Customizing Desktop Assistant notifications using API parameters

    ServiceNow administrators can customize and send Desktop Assistant notifications to targeted users by leveraging theDesktopAppNotificationUtilsscript include and itssendDANotification()method. This enables timely communication of critical events, such as major incidents or expiring software licenses, directly on users’ endpoint devices via the Desktop Assistant client.

    Show full answer Show less

    The API method is server-side only and can be invoked from business rules, background scripts, scheduled jobs, Flow Designer actions, or flow script steps. It is not accessible through REST endpoints or the Notify API. Note that the Desktop Assistant client must be installed and running on user devices to receive notifications.

    Notification Delivery Process

    • Triggering: A server-side process calls sendDANotification() with appropriate parameters.
    • Validation and Storage: The API validates inputs and creates a record in the sndexdesktopassistantnotification table containing notification details and recipients.
    • Asynchronous Processing: The creation of the record triggers a background flow (desktopassistantnotificationcall) that prepares and queues notifications for delivery.
    • Queuing: The background flow inserts delivery attempts into the sndexdesktopnotifyqueue table, with each row representing a delivery attempt to a device token.
    • Delivery to Endpoints: The Agent Client Collector (ACC) on user devices polls the queue upon receiving the sndexdesktop.triggerCheckdef event and delivers notifications to the Desktop Assistant client.

    Notification Appearance and Behavior

    • Notifications appear as cards in the Desktop Assistant notification panel, showing the title, message, and timestamp.
    • If linked to a ServiceNow record, the card includes a deep link for quick access.
    • A brief system tray toast notification appears on active devices when a notification is delivered; this toast automatically disappears, while the card remains for later viewing.

    Notification Visibility Control

    The duration notifications remain visible in the Desktop Assistant client is controlled by the system property sndexdesktop.sndesktopassistant.notificationtimetolive. Administrators can set this from 1 to 7 days, with a default of 7 days. Notifications expire after this period and are removed automatically.

    Practical Benefits for ServiceNow Customers

    • Enables flexible, targeted communication to users about critical and time-sensitive issues.
    • Supports automated notification delivery integrated into ServiceNow processes and workflows.
    • Provides rich notification content with deep linking to relevant ServiceNow records.
    • Allows control over notification visibility duration to manage end-user experience effectively.

    Administrators can send customized Desktop Assistant notifications to specific users by using the DesktopAppNotificationUtils script include with a set of notification parameters.

    Desktop Assistant notifications are sent using the sendDANotification() method of the DesktopAppNotificationUtils script include in the sn_dex_desktop application scope. This method is a server-side invocation that can be called from business rules, Background Scripts, Scheduled Jobs, Flow Script Steps, or Flow Designer actions. It is not exposed as a REST endpoint or Notify API. The Desktop Assistant client receives these notifications and displays them on the user's device, notifying employees of time-sensitive events such as major incidents affecting their services or software licenses that are about to expire.

    By default, Major Incident Management (MIM) and Proactive Engagement (PE) send notifications through Desktop Assistant without invoking this API. For more information, see Desktop Assistant notifications. Use the DesktopAppNotificationUtils API to send notifications from additional sources.

    Note:
    Desktop Assistant notifications require the Desktop Assistant client to be installed and running on the user's endpoint device.

    Desktop Assistant notification delivery process

    1. Server-side trigger: A server-side component such as a business rule, Flow Designer action, or Scheduled Job initiates the notification delivery process by calling the sendDANotification() method on the DesktopAppNotificationUtils script include.
    2. Validation and record creation: The script include validates the input parameters and inserts a record into the Desktop Assistant notification (sn_dex_desktop_assistant_notification) table if validation succeeds. This record stores the notification title, message body, recipient list or device list, source, and expiry date.
    3. Asynchronous background processing: Creating the notification record triggers the desktop_assistant_notification_call background flow. This flow runs asynchronously, allowing the original caller to continue without waiting for delivery processing to complete.
    4. Notification preparation and queuing: The background flow calls the internal DesktopNotificationAPI.sendNotification() method, which prepares the notification for delivery and inserts rows into the Desktop Assistant Notification Queue (sn_dex_desktop_notify_queue) table. Each row in this table represents one delivery attempt for one device token.
    5. Notification delivery to the endpoint: The Agent Client Collector (ACC) running on the end user's device retrieves pending entries from the queue and delivers the notification to the Desktop Assistant client.

      By default, notification delivery is event-driven. The platform triggers the sn_dex_desktop.triggerCheckdef event, which signals the ACC agent to check for new notifications.

    How notifications appear in the Desktop Assistant client

    Each Desktop Assistant notification appears as a card in the Desktop Assistant notification panel. The notification card displays the title, message body, and a timestamp indicating when the notification was sent.

    If a notification is associated with a ServiceNow record, the card includes a deep link that opens the linked record directly. When the user's device is active at notification delivery time, a brief system tray toast notification also appears. The toast disappears automatically, while the notification card remains available in the Desktop Assistant panel for later reference.

    Notification visibility duration

    The sn_dex_desktop.sn_desktop_assistant.notification_time_to_live system property controls notification visibility duration in the Desktop Assistant client. You can set this value from 1 to 7 days, with a default of 7 days. If a value greater than 7 days is configured, the visibility period is limited to seven days. After the notification reaches its expiry date, it is automatically removed from the Desktop Assistant notification panel.