Configure code for critical alerts

  • Release version: Xanadu
  • Updated August 1, 2024
  • 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 tailored for iOS and Android devices within the ITSM business unit. By adding specific JSON code in the Push message content area, customers can enable notifications to behave as critical alerts, which override certain device settings to ensure urgent attention.

    Show full answer Show less

    Key Features

    • Platform-specific JSON configuration: Distinct JSON code snippets are required for iOS and Android platforms to activate critical alerts properly.
    • Android-specific behavior considerations: On some Android devices (e.g., OnePlus, Oppo), physical ringer switches or Do Not Disturb (DND) modes may affect how critical alerts behave.
    • Critical alert JSON for Android: Includes setting the notification priority to "high" to wake devices and trigger critical alerts.
    • Critical alert JSON for all operating systems: Defines sound parameters such as critical (1 to activate), name (sound file name), and volume (0.1 to 1.0 range) to customize alert tones.
    • Available alert tones: Several predefined sound files (e.g., NotificationAlert-2.caf, NotificationAlert-9.caf) can be used to customize the critical alert sound.
    • ITSM CriticalPushPayloadBuilder script include: For ITSM customers, a reusable server-side script include called CriticalPushPayloadBuilder may already exist to handle critical alert JSON generation, reducing manual coding effort.

    Practical Implementation

    • Insert the provided JSON code in the Push message content area to define critical alerts for both iOS and Android.
    • Ensure the Android JSON snippet sets the notification priority to high to wake devices.
    • Define or customize the alert sound using the sound object with parameters critical, name, and volume.
    • If using ITSM, confirm whether the CriticalPushPayloadBuilder script include is in place; it simplifies critical alert setup and centralizes configuration.
    • Be aware that modifying the script include affects all ITSM implementations, and upgrades may override changes.

    Key Outcomes

    By correctly configuring the JSON code for critical alerts, ServiceNow customers can ensure that push notifications are delivered with high urgency, overriding device settings like silent or DND modes where possible. This enhances incident response effectiveness by making critical notifications more noticeable across supported devices. Using the ITSM script include streamlines maintenance and consistency across critical alert implementations.

    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.