API parameters to configure Desktop Assistant notifications
Summarize
Summary of API parameters to configure Desktop Assistant notifications
ThesendDANotification()method in theDesktopAppNotificationUtilsscript include enables configuration of Desktop Assistant notifications in ServiceNow. This API lets you control notification content, recipients, linking behavior, and source application, ensuring notifications are delivered accurately and linked to relevant records.
Show less
Key Features
- notificationmessage: Required body text for the notification card; must be a non-empty string up to 1000 characters, or the API returns a 400 error.
- notificationtitle: Optional title text for the notification card; if omitted or invalid, an empty title is shown without error.
- recipientlist: Comma-separated sysid values of users from the User (sysuser) table who will receive the notification.
- referrerid and referrertable: Together define the record linked by the notification; both must be provided to ensure correct linking behavior.
- source: Defines the triggering application, accepting only 'mim' (Major Incident Management) or 'pe' (Proactive Engagement), case-insensitive. Invalid values cause a 400 error.
Parameter Interactions and Behavior
- Missing or invalid notificationmessage results in a 400 error.
- Missing or invalid notificationtitle displays an empty title but no error.
- Invalid source values produce a 400 error indicating missing source record.
- If enablepushnotification is false, the API immediately returns a 400 error without creating records or triggering flows.
- notificationtimetolive defaults to 7 days and is capped at 7 days maximum.
- Providing only one of referrerid or referrertable stores both fields but may cause incorrect notification linking.
Notification Card Element Mapping
- Title (card header) is populated from notificationtitle.
- Body text comes from notificationmessage.
- Timestamp is derived internally from the syscreatedon field in the notification queue record (not an API parameter).
- The system tray notification appears when the notification status is Pending during client checks (not controlled via API).
Practical Implications for ServiceNow Customers
By correctly setting these parameters when calling sendDANotification(), customers can ensure that Desktop Assistant notifications are delivered with appropriate content, linked to relevant records, and sourced from recognized applications. Attention to required fields and valid values avoids errors and guarantees the notification experience is seamless for end users.
sendDANotification() method parameters in the DesktopAppNotificationUtils script include for configuring Desktop Assistant notifications.
| Parameter | Description |
|---|---|
| notification_message |
Body text displayed on the notification card. The value must be a non-empty string and not exceed 1000 characters. If this condition is not met, the API returns a 400 error. |
| notification_title |
Title text displayed at the top of the Desktop Assistant notification card. If omitted, the notification card displays an empty title without raising an error. |
| recipient_list |
The |
| referrer_id |
The sys_id of the record that the notification links to. This parameter works in combination with referrer_table. If only one of these two parameters is provided, the link behavior is unpredictable. |
| referrer_table |
The name of the table containing the record that the notification links to. For example, incident or sc_request. This parameter works in combination with referrer_id. If only one of these two parameters is provided, the link behavior is unpredictable. |
| source | The source application that triggered the notification. Accepted values are mim (Major Incident Management) and pe (Proactive Engagement). The value is case-insensitive. Any other value causes the API to return a 400 error. Note: Desktop Assistant sends notifications for a new source only if the source is added as a choice value in the Notification source field of the Desktop Assistant notification (sn_dex_desktop_assistant_notification) table. This enables Desktop Assistant to recognize and track the source. |
Parameter interactions and precedence
| Scenario | Behavior |
|---|---|
| notification_message is empty, missing, or not a string value. | Returns a 400 error. |
| notification_title is missing or not a string value. | The Desktop Assistant client displays an empty title. No error is raised. |
| source is not mim or pe | Returns a 400 error: Source record missing in Desktop Assistant Notification Source table |
| enable_push_notification is false | Returns a 400 error immediately. No record is created and no flow runs. |
| notification_time_to_live is set to more than 7 days | The value is capped at seven days. |
| notification_time_to_live property is not set | Defaults to seven days. |
| Only one of referrer_table or referrer_id is provided | No error is raised and both fields are stored, but the notification on the Desktop Assistant client may not link to the correct record. |
Desktop Assistant notification card element‑to‑source mapping
| Desktop Assistant client UI element | Source parameter or field |
|---|---|
| Notification title (card header) | notification_title |
| Notification body text | notification_message |
| Timestamp | Derived from the sys_created_on field on the Desktop Assistant Notification Queue (sn_dex_desktop_notify_queue) record. Not an API parameter. |
| System tray notification | Displayed when the notification status is Pending at the time the Desktop Assistant client checks for new notifications. Not an API parameter. |