Key Parameters and Their Use

• notificationmessage: The main body text on the notification card. It must be a non-empty string up to 1000 characters. Invalid values cause a 400 error, so ensure this is always populated correctly.
• notificationtitle: The title shown at the top of the notification card. This is optional; if omitted or invalid, the notification shows an empty title without error.
• recipientlist: A comma-separated string of sysid values from the User (sysuser) table representing the notification recipients. This enables precise targeting of notifications.
• referrerid and referrertable: Together, these link the notification to a specific record (e.g., incident or screquest). Both must be provided for reliable linking; providing only one results in unpredictable behavior in the notification's link.
• source: Identifies the application triggering the notification. Acceptable values are mim (Major Incident Management) and pe (Proactive Engagement), case-insensitive. Other values produce a 400 error. The source must be defined as a choice in the sndexdesktopassistantnotification table for Desktop Assistant to recognize and track it.

Parameter Validation and Behavior

• If notificationmessage is missing, empty, or not a string, the API returns a 400 error.
• If notificationtitle is missing or invalid, the notification displays without a title, but no error occurs.
• If source is invalid (not "mim" or "pe"), a 400 error is returned indicating a missing source record.
• When enablepushnotification is false, the API returns a 400 error immediately with no notification created.
• notificationtimetolive defaults to seven days and is capped at a maximum of seven days if set higher.
• Providing only one of referrerid or referrertable does not cause an error but may result in incorrect notification linking.

Notification Display Elements

• Notification title on the card derives from notificationtitle.
• Notification body text on the card comes from notificationmessage.
• Timestamp is automatically derived from the syscreatedon field of the notification queue record and is not set via the API.
• System tray notification appears when notification status is "Pending" at the time the Desktop Assistant client checks for new notifications; this is also not an API parameter.

Practical Considerations for ServiceNow Customers

When configuring Desktop Assistant notifications via the API, ensure all required fields meet validation rules to avoid errors. Use the recipientlist to target specific users accurately. Always provide both referrerid and referrertable together to maintain proper link behavior in notifications. Confirm that the source value is registered in the Desktop Assistant notification source table to enable recognition and tracking.

These guidelines help you deliver clear, actionable notifications that integrate seamlessly with Desktop Assistant, improving user engagement and response times.