Configure code for critical alerts

  • Release version: Yokohama
  • Updated January 30, 2025
  • 3 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 Configure code for critical alerts

    This guide explains how to configure push notifications as critical alerts in ServiceNow, specifically for iOS and Android devices, including considerations for the IT Service Management (ITSM) business unit. Adding specific JSON code to the Push message content area enables these notifications to trigger critical alert behavior on mobile devices.

    Show full answer Show less

    Key Configuration Details

    • Platform-specific JSON code: Different JSON structures are required for iOS and Android devices to activate critical alerts.
    • Android critical alert JSON: The JSON must include a priority setting of "high" to ensure the device wakes up and triggers the critical alert sound, even overriding some device settings such as Do Not Disturb, although this behavior depends on device models (notably OnePlus and Oppo).
    • iOS critical alert JSON: The JSON must specify the sound parameters with critical: 1, the sound file name (e.g., NotificationAlert-1.caf), and the volume level (0.1 to 1.0). If no sound name is specified, the default app or device ringtone is used.
    • Sound options: Several predefined sound files are available for critical alerts, each with distinct tones and rhythms to suit alert severity.

    Example JSON Code

    The complete JSON to enable critical alerts for both Android and iOS includes:

    json["sncGoogleKeys"] = { "android": { "priority": "high" }, "priority": "high"};json["aps"]["sound"] = { "critical": 1, "name": "NotificationAlert-1.caf", "volume": 1.0};

    ITSM Business Unit Considerations

    • The ITSM business unit may already include a reusable script include named CriticalPushPayloadBuilder in the Push message content area, which automates critical alert configuration.
    • This script include can be called as CriticalPushPayloadBuilder(current, json, attributes).buildJSON() and manages the JSON construction for critical alerts.
    • To customize sound volume, tone, or toggle critical alert status, adjustments must be made within the input parameters of this script include.
    • Be aware that updates or upgrades to the ITSM plugin may override customizations to this script include.

    Important Notes

    • On certain Android devices (such as OnePlus and Oppo), hardware or system settings like physical ringer switches or Do Not Disturb mode may limit the app’s ability to fully control notification sounds.
    • Both iOS and Android JSON configurations must be included to support users with mixed-device environments.

    You can make a push notification into a critical alert with the addition of some JSON code. Different JSON code is used for iOS and Android operating systems and for the ITSM business unit.

    When creating critical alert notifications, you need the code structure of a push notification message as well as the required JSON code that defines the notification as a critical alert. You add this code in the Push message content area. For more information, see Mobile critical alerts.

    Important:

    On the Android platform, when a user receives a critical alert on certain phone types, they may experience the following device behavior:

    OnePlus devices with hardware-controlled ringer mode:
    On devices like OnePlus where the ringer mode is controlled by a physical switch, the app might not be able to override the notification sound volume if the device is set to silent or vibrate mode.
    OnePlus or Oppo device Do Not Disturb mode behavior:
    On certain devices, like Oppo and OnePlus, if Do Not Disturb (DND) mode is enabled, the DND setting might be temporarily turned off until the critical notification sound has finished playing.

    Critical alert JSON to activate Android operating systems

    The following code must be added to the JSON code because it activates Android devices to wake up so that a critical alert can be triggered.
    Note:
    Because users use both iOS and Android devices you must add this code. The JSON entry in the code is a returned dictionary name value from the scripting.
     

json["sncGoogleKeys"] = { 
          "android": { 
              "priority": "high" 
          }, 
          "priority": "high" 
      };

    Critical alert JSON for all operating systems

    The following JSON must be added so that a notification behaves as a critical alert.

    var json = {};
json["aps"] = { 
"sound": {
          "critical": 1, 
          "name": "NotificationAlert-1.caf", 
          "volume": 1.0 
}
      };
    The parameters in the sample JSON code are as follows:
    • The critical parameter defines the notification as a critical alert. 1 means the critical alert is active, 0 means the critical alert is inactive.
    • The name parameter is the name of the tone that is activated when a critical alert is sent. Some tones for critical alerts are listed in the table. For a complete list, see Configure sounds for push notifications.
      Accepted file name values Tone rhythm
      NotificationAlert-2.caf Dramatic
      NotificationAlert-2-Short.caf Dramatic
      NotificationAlert-9.caf Dramatic, Powerful
      NotificationAlert-9-Short.caf Dramatic, Powerful
      NotificationAlert-10.caf Dramatic, Suspenseful
      NotificationAlert-10-Short.caf Dramatic, Suspenseful
      Note:
      If a name value isn’t defined, the system uses the application’s default ringtone. If an application doesn't have a defined ringtone, then the system uses the device's default ringtone.
    • The volume parameter defines the volume of the critical alert sound. The range is from 0.1 as the quietest to 1.0 as the loudest.

    Example JSON code block for critical alert

    The following is a complete example block of JSON code that you must add and configure to activate a critical alert for Android and iOS devices.

    json["sncGoogleKeys"] = { 
          "android": { 
              "priority": "high" 
          }, 
          "priority": "high" 
      }; 
  
json["aps"]["sound"] = { 
          "critical": 1, 
          "name": "NotificationAlert-1.caf", 
          "volume": 1.0 
      };

    IT Service Management (ITSM) CriticalPushPayloader script include

    The Push message content area may contain previously configured code including the script include CriticalPushPayLoadBuilder, created by the ITSM business unit. If so, then no additional configuration is required for critical alerts. Script includes  are reusable server-side script logic that define a function or class.  CriticalPushPayLoadBuilder is a script include that contains functions to support critical alerts. The call of the script includes looks like this: CriticalPushPayloadBuilder (current, json, attributes).buildJSON()
    Note:
    If you need to change the values of the Volume or Name parameters, or change the alert from critical to non-critical, you need to access the function parameters that the script include is getting as inputs.

    Changing the value of the critical alert script include affects all ITSM implementations of the script include. Similarly, an ITSM plugin upgrade could override your changes to your script include.