Alarm Management Open API

  • Release version: Zurich
  • Updated July 31, 2025
  • 24 minutes to read

    • The Alarm Management Open API provides endpoints to create, update, and retrieve data from the Events [em_event] and Alert [em_alert] tables.

    The telecommunications Alarm Management Open API (sn_ind_tmf642) is a ServiceNow® implementation of the TM Forum Open API specification. This API is based on the TMF642 Alarm Management API User Guide v5.0.0, September 2023.

    The calling user must have to access the sn_ind_tmf642.alarm_mgmt_integration endpoint.

    This API is provided within the sn_ind_tmf642 namespace.

    The TM Forum Open API specification requires a synchronous response for every inbound request it receives. Apply correlation and de-duplication in the source operational support system (OSS) before forwarding payloads to the system.

    This API can be extended to make customizations around required parameters, request body validation, additional REST operations, and field mappings. For more information, see the Alarm Management Open API Developer Guide.

    The Alarm Management Open API is conformance certified by TM Forum.

    TMF conformance logo

    Alarm Management Open API – GET /sn_ind_tmf642/alarm_mgmt/alarm

    Retrieves a list of all alarm records from the Events [em_event] and Alert [em_alert] tables.

    URL format

    Default URL: /api/sn_ind_tmf642/alarm_mgmt/alarm

    Supported request parameters

    Table 1. Path parameters
    Name Description
    None
    Table 2. Query parameters
    Name Description
    alarmRaisedTime Date the alarm was raised. Only alarms with a date matching the value of this parameter are returned in the response.

    Data type: String
    fields List of fields to return in the response. Invalid fields are ignored.
    Valid fields:
    • alarmedObject
    • alarmRaisedTime
    • alarmType
    • crossedThresholdInformation
    • externalAlarmId
    • id
    • perceivedSeverity
    • probableCause
    • source
    • sourceSystemId
    • state
    • type

    Default: All fields

    Data type: String
    id Alarm ID. Only alarms with an ID matching the value of this parameter are returned in the response.

    Data type: String

    Table: In the Message key field in the Events [em_event] table.
    limit Maximum number of records to return. For requests that exceed this number of records, use the offset parameter to paginate record retrieval.

    Default: 1000

    Maximum: 2000

    Data type: Number
    offset Starting index at which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks.

    Data type: Number

    Default: 0
    probableCause Probable cause of the alarm. Only alarms with a probable cause matching the value of this parameter are returned in the response.

    Data type: String
    state Alarm state. Only alarms with a state matching the value of this parameter are returned in the response.

    Data type: String
    sourceSystemId Source system ID of the alarm. Only alarms with a source system ID matching the value of this parameter are returned in the response.

    Data type: String
    Table 3. Request body parameters (JSON)
    Name Description
    None

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 4. Request headers
    Header Description
    None
    Table 5. Response headers
    Header Description
    Content-Range Range of content returned in a paginated call.

    For example, if offset=2 and limit=3, the value of the Content-Range header is items 3-5.
    Content-Type Data format of the response body. Only supports application/json.
    Link Contains the following links to navigate through query results.
    • first
    • last
    • next
    • previous
    X-Total-Count For paginated queries, this header specifies the total number of records available on the server.

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 6. Status codes
    Status code Description
    200 Request successfully processed. Full resource returned in response (no pagination).
    206 Partial resource returned in response (with pagination).
    400
    Bad request. Possible reasons:
    • Invalid path parameter
    • Invalid URI
    404 Record not found. No records matching the query parameters are found in the table.

    Response body parameters (JSON)

    Name Description
    affectedService List of one or more services affected by the alarm.

    Data type: Array of Objects

    "affectedService":[
  {
    "href": "String",
    "id": "String"
  },
]
    affectedService.href URL reference that provides details of the affected service.

    Data type: String
    affectedService.id Identifier of the service affected by the alarm. This value maps to the affected configuration item (CI) on the alert.

    Data type: String
    alarmDetails Additional details about the alarm.

    Data type: String
    alarmedObject Details of the alarm object. 
    "alarmedObject":
{
  "href": "String",
  "id": "String"
}

    Data type: Object
    alarmedObject.id Unique identifier of the alarm object. This value maps to a CI in the system.

    Data type: String
    alarmedObject.href
    URL reference to get the details of the alarm object.

    Data type: String
    alarmedObjectType Type or class of object associated with the event.

    Data type: String
    alarmRaisedTime Date and time at which the alarm occurs at its source.

    Data type: String
    alarmReportingTime Date and time at which the OSS reports its alarm.
    This value might differ from the alarmRaisedTime value. For example, if an element management system (EMS) maintains the alarm list:
    • The alarmRaisedTime is the time of alarm detection by the network element (NE).
    • The alarmReportingTime is the alarm report time of storage in the EMS alarm list.

    Data type: String
    alarmType Alarm category.

    Data type: String
    crossedThresholdInformation Details about the crossed threshold.

    Data type: Object

    "crossedThresholdInformation":
{
  "direction": "String",
  "granularity": "String",
  "indicatorName": "String",
  "indicatorUnit": "String",
  "observedValue": "String",
  "thresholdCrossingDescription": "String",
  "thresholdId": "String",
  "thresholdRef": "String"
}
    crossedThresholdInformation.direction Threshold crossing direction.
    Valid values:
    • DOWN
    • UP

    Data type: String
    crossedThresholdInformation.granularity Granularity at which the indicator is evaluated for threshold crossing. For example, 5MINUTES.

    Data type: String
    crossedThresholdInformation.indicatorName Name of the indicator that crosses the alarm threshold.

    Data type: String
    crossedThresholdInformation.indicatorUnit Measurement unit of the indicator corresponding to the crossed threshold.

    Data type: String
    crossedThresholdInformation.observedValue Number identifying the indicator crossing the threshold.

    Data type: String
    crossedThresholdInformation.thresholdCrossingDescription More threshold details of the threshold crossing alarm.

    Data type: String
    crossedThresholdInformation.thresholdId Unique identifier of the threshold that caused the alarm.

    Data type: String
    crossedThresholdInformation.thresholdRef URL of the threshold object.

    Data type: String
    externalAlarmId Unique identifier for the alarm from the source system posting the alarm.

    Data type: String
    href URL of the resource.

    Data type: String
    id Unique identifier for the system to identify and process the alarm payload as an event.

    Data type: String
    perceivedSeverity Alarm severity.
    Valid values:
    • CLEAR
    • CRITICAL
    • MAJOR
    • MINOR
    • WARNING

    Data type: String
    plannedOutageIndication Indicates that the managed object for this alarm is in a planned outage state. For example, planned maintenance or out-of-service.

    Data type: String
    probableCause Most likely situation to trigger the alarm. Use with alarmType to qualify the alarm.

    Data type: String
    proposedRepairActions If available to the system, provides a repair action to resolve the issue that triggers the alarm.

    Data type: String
    serviceAffecting Flag that indicates whether the alarm affects service.
    Valid values:
    • true: Alarm affects service performance or availability.
    • false: Alarm doesn't affect service.

    Default: false

    Data type: Boolean
    sourceSystemId Instance ID of the source alarm.

    Data type: String
    specificProblem Specific problem that triggers the alarm. Use with the probableCause tparameter o qualify the alarm.

    Data type: String
    state Alarm state.
    Valid values:
    • Error
    • Ignored
    • Ready
    • Processed
    If an invalid value is provided, the state is set to Ready.

    If the state is Ready, an alert is created in the Alert [em_alert] table and the state then becomes Processed.

    If the state is Processed, Ignored, or Error no alert is created.

    Default value: Ready

    Data type: String

    cURL request

    This example retrieves all alarms.

    curl "https://instance.servicenow.com/api/sn_ind_tmf642/alarm_mgmt/alarm" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

    Response body.

    [
   {
      "externalAlarmId": "2212331",
      "alarmType": "QualityOfServiceAlarm23",
      "perceivedSeverity": "MAJOR",
      "probableCause": "ProbB",
      "sourceSystemId": "checkSB",
      "alarmedObject": {
         "id": "vManage_000000",
         "href": " http://api/alarmedobject/000000"
      },
      "crossedThresholdInformation": {
         "direction": "111",
         "granularity": "1234",
         "indicatorName": "sdfgds",
         "indicatorUnit": "asdfdsaf",
         "observedValue": "adsfds",
         "thresholdId": "12fasdfasdfasd",
         "thresholdCrossingDescription": "S23rtring",
         "thresholdRef": "asdfasf"
      },
      "type": "QualityOfServiceAlarm",
      "ackState": "acknowledged",
      "specificProblem": "Inbound Traffic threshold crossed",
      "alarmedObjectType": "ROUTER",
      "alarmDetails": "Software Failure on SD-WAN Controller vManage_000000",
      "state": "processed",
      "alarmChangedTime": "2017-08-15T07:04:15.666Z",
      "proposedRepairActions": "Switch in standby equipment",
      "alarmReportingTime": "2017-06-15T07:04:15.666Z",
      "alarmRaisedTime": "2020-09-15T14:04:15.000Z",
      "plannedOutageIndication": "IN_SERVICE",
      "serviceAffecting": true,
      "affectedService": [
         {
            "id": "SD WAN Enterprise Solutions",
            "href": "http://api/service/vlan_dot0_dot0"
         },
         {
            "id": "Santa Clara SD WAN Application Service",
            "href": "http://api/service/vlan_dot0_dot0"
         }
      ],
      "source": "Alarm Management Open API",
      "href": "/api/sn_ind_tmf642/alarm_mgmt/alarm/001a0ca629078d10f87759e2f69e4c64_2212331",
      "id": "001a0ca629078d10f87759e2f69e4c64_2212331"
   },
   {
      "externalAlarmId": "2212331",
      "alarmType": "QualityOfServiceAlarm23",
      "perceivedSeverity": "MAJOR",
      "probableCause": "ProbB",
      "sourceSystemId": "checkSB",
      "alarmedObject": {
         "id": "vManage_000000",
         "href": " http://api/alarmedobject/000000"
      },
      "crossedThresholdInformation": {
         "direction": "111",
         "granularity": "1234",
         "indicatorName": "sdfgds",
         "indicatorUnit": "asdfdsaf",
         "observedValue": "adsfds",
         "thresholdId": "12fasdfasdfasd",
         "thresholdCrossingDescription": "S23rtring",
         "thresholdRef": "asdfasf"
      },
      "type": "QualityOfServiceAlarm",
      "ackState": "acknowledged",
      "specificProblem": "Inbound Traffic threshold crossed",
      "alarmedObjectType": "ROUTER",
      "alarmDetails": "Software Failure on SD-WAN Controller vManage_000000",
      "state": "processed",
      "alarmChangedTime": "2017-08-15T07:04:15.666Z",
      "proposedRepairActions": "Switch in standby equipment",
      "alarmReportingTime": "2017-06-15T07:04:15.666Z",
      "alarmRaisedTime": "2020-09-15T14:04:15.000Z",
      "plannedOutageIndication": "IN_SERVICE",
      "serviceAffecting": true,
      "affectedService": [
         {
            "id": "SD WAN Enterprise Solutions",
            "href": "http://api/service/vlan_dot0_dot0"
         },
         {
            "id": "Santa Clara SD WAN Application Service",
            "href": "http://api/service/vlan_dot0_dot0"
         }
      ],
      "source": "Alarm Management Open API",
      "href": "/api/sn_ind_tmf642/alarm_mgmt/alarm/001c84aa29078d10f87759e2f69e4cfa_2212331",
      "id": "001c84aa29078d10f87759e2f69e4cfa_2212331"
   }
]

    Alarm Management Open API – GET /sn_ind_tmf642/alarm_mgmt/alarm/{id}

    Retrieves a specified alarm record from the Events [em_event] or Alert [em_alert] table.

    URL format

    Default URL: /api/sn_ind_tmf642/alarm_mgmt/alarm/{id}

    Supported request parameters

    Table 7. Path parameters
    Name Description
    id Unique identifier of the record to retrieve.

    Data type: String

    Table: In the Message key field of the Events [em_event] table.
    Table 8. Query parameters
    Name Description
    fields List of fields to return in the response. Invalid fields are ignored.
    Valid fields:
    • alarmedObject
    • alarmRaisedTime
    • alarmType
    • crossedThresholdInformation
    • externalAlarmId
    • id
    • perceivedSeverity
    • probableCause
    • source
    • sourceSystemId
    • state
    • type

    Default value: All fields

    Data type: String
    Table 9. Request body parameters (JSON)
    Name Description
    None

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 10. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json.
    Table 11. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 12. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    400 Bad Request. A bad request type or malformed request was detected for one or more of the following reasons.
    • Invalid path parameter.
    • Invalid URI.
    404 Record not found. A record associated with the specified ID is not found in the Event [em_event] or Alert [em_alert] table.

    Response body parameters (JSON)

    Name Description
    affectedService List of one or more services affected by the alarm.

    Data type: Array of Objects

    "affectedService":[
  {
    "href": "String",
    "id": "String"
  },
]
    affectedService.href URL reference that provides details of the affected service.

    Data type: String
    affectedService.id Identifier of the service affected by the alarm. This value maps to the affected configuration item (CI) on the alert.

    Data type: String
    alarmDetails Additional details about the alarm.

    Data type: String
    alarmedObject Details of the alarm object.

    Data type: Object

    "alarmedObject":
{
  "href": "String",
  "id": "String"
}
    alarmedObject.id Unique identifier of the alarm object. This value maps to a CI in the system.

    Data type: String
    alarmedObject.href
    URL reference to get the details of the alarm object.

    Data type: String
    alarmedObjectType Type or class of object associated with the event.

    Data type: String
    alarmRaisedTime Date and time at which the alarm occurs at its source.

    Data type: String
    alarmReportingTime Date and time at which the OSS reports its alarm.
    This value might differ from the alarmRaisedTime value. For example, if an element management system (EMS) maintains the alarm list:
    • The alarmRaisedTime is the time of alarm detection by the network element (NE).
    • The alarmReportingTime is the alarm report time of storage in the EMS alarm list.

    Data type: String
    alarmType Alarm category.

    Data type: String
    crossedThresholdInformation Details about the crossed threshold.

    Data type: Object

    "crossedThresholdInformation":
{
  "direction": "String",
  "granularity": "String",
  "indicatorName": "String",
  "indicatorUnit": "String",
  "observedValue": "String",
  "thresholdCrossingDescription": "String",
  "thresholdId": "String",
  "thresholdRef": "String"
}
    crossedThresholdInformation.direction Threshold crossing direction.
    Valid values:
    • DOWN
    • UP

    Data type: String
    crossedThresholdInformation.granularity Granularity at which the indicator is evaluated for threshold crossing. For example, 5MINUTES.

    Data type: String
    crossedThresholdInformation.indicatorName Name of the indicator that crosses the alarm threshold.

    Data type: String
    crossedThresholdInformation.indicatorUnit Measurement unit of the indicator corresponding to the crossed threshold.

    Data type: String
    crossedThresholdInformation.observedValue Number identifying the indicator crossing the threshold.

    Data type: String
    crossedThresholdInformation.thresholdCrossingDescription More threshold details of the threshold crossing alarm.

    Data type: String
    crossedThresholdInformation.thresholdId Unique identifier of the threshold that caused the alarm.

    Data type: String
    crossedThresholdInformation.thresholdRef URL of the threshold object.

    Data type: String
    externalAlarmId Unique identifier for the alarm from the source system posting the alarm.

    Data type: String
    href URL of the resource.

    Data type: String
    id Unique identifier for the system to identify and process the alarm payload as an event.

    Data type: String
    perceivedSeverity Alarm severity.
    Valid values:
    • CLEAR
    • CRITICAL
    • MAJOR
    • MINOR
    • WARNING

    Data type: String
    plannedOutageIndication Indicates that the managed object for this alarm is in a planned outage state. For example, planned maintenance or out-of-service.

    Data type: String
    probableCause Most likely situation to trigger the alarm. Use with alarmType to qualify the alarm.

    Data type: String
    proposedRepairActions If available to the system, provides a repair action to resolve the issue that triggers the alarm.

    Data type: String
    serviceAffecting Flag that indicates whether the alarm affects service.
    Valid values:
    • true: Alarm affects service performance or availability.
    • false: Alarm doesn't affect service.

    Default: false

    Data type: Boolean
    sourceSystemId Instance ID of the source alarm.

    Data type: String
    specificProblem Specific problem that triggers the alarm. Use with the probableCause tparameter o qualify the alarm.

    Data type: String
    state Alarm state.
    Valid values:
    • Error
    • Ignored
    • Ready
    • Processed
    If an invalid value is provided, the state is set to Ready.

    If the state is Ready, an alert is created in the Alert [em_alert] table and the state then becomes Processed.

    If the state is Processed, Ignored, or Error no alert is created.

    Default value: Ready

    Data type: String

    cURL request

    This example retrieves an alarm.

    curl "https://instance.servicenow.com/api/sn_ind_tmf642/alarm_mgmt/alarm/001a0ca629078d10f87759e2f69e4c64_2212331" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

    Response body.

    {
   "externalAlarmId": "2212331",
   "alarmType": "QualityOfServiceAlarm23",
   "perceivedSeverity": "MAJOR",
   "probableCause": "ProbB",
   "sourceSystemId": "checkSB",
   "alarmedObject": {
      "id": "vManage_000000",
      "href": " http://api/alarmedobject/000000"
   },
   "crossedThresholdInformation": {
      "direction": "111",
      "granularity": "1234",
      "indicatorName": "ind_name",
      "indicatorUnit": "ind_unit",
      "observedValue": "232",
      "thresholdId": "200",
      "thresholdCrossingDescription": "sample_description",
      "thresholdRef": "sample_ref"
   },
   "type": "QualityOfServiceAlarm",
   "ackState": "acknowledged",
   "specificProblem": "Inbound Traffic threshold crossed",
   "alarmedObjectType": "ROUTER",
   "alarmDetails": "Software Failure on SD-WAN Controller vManage_000000",
   "state": "processed",
   "alarmChangedTime": "2017-08-15T07:04:15.666Z",
   "proposedRepairActions": "Switch in standby equipment",
   "alarmReportingTime": "2017-06-15T07:04:15.666Z",
   "alarmRaisedTime": "2020-09-15T14:04:15.000Z",
   "plannedOutageIndication": "IN_SERVICE",
   "serviceAffecting": true,
   "affectedService": [
      {
         "id": "SD WAN Enterprise Solutions",
         "href": "http://api/service/vlan_dot0_dot0"
      },
      {
         "id": "Santa Clara SD WAN Application Service",
         "href": "http://api/service/vlan_dot0_dot0"
      }
   ],
   "source": "Alarm Management Open API",
   "href": "/api/sn_ind_tmf642/alarm_mgmt/alarm/001a0ca629078d10f87759e2f69e4c64_2212331",
   "id": "001a0ca629078d10f87759e2f69e4c64_2212331"
}

    Alarm Management Open API – PATCH /sn_ind_tmf642/alarm_mgmt/alarm/{id}

    Updates a specified alarm and any associated alert.

    This endpoint writes the response body to the Additional Info field of the event record in the Events [em_event] table.

    URL format

    Default URL: /api/sn_ind_tmf642/alarm_mgmt/alarm/{id}

    Supported request parameters

    Table 13. Path parameters
    Name Description
    id Unique identifier of the record to update.

    Data type: String

    Table: In the Message key field of the Events [em_event] table.
    Table 14. Query parameters
    Name Description
    None
    Table 15. Request body parameters (JSON)
    Name Description
    affectedService List of one or more services affected by the alarm.

    Data type: Array of Objects

    "affectedService":[
  {
    "href": "String",
    "id": "String"
  },
]
    affectedService.href URL reference that provides details of the affected service.

    Data type: String
    affectedService.id Required.
    Identifier of the service affected by the alarm. This value maps to the affected configuration item (CI) on the alert.

    Data type: String
    alarmChangedTime Indicates the last date and time the alarm changed on the alarm-owning system. Any change to the alarm updates this value whether coming from the alarmed resource or triggered by a change from the client.

    Data type: String
    alarmDetails Additional details about the alarm.

    Data type: String
    alarmEscalation

    Flag that indicates an escalation in alarm severity.

    Valid values:
    • true: There is an escalation in alarm severity.
    • false: The alarm severity is the same or lower.

    Default: false

    Data type: Boolean
    crossedThresholdInformation Details about the crossed threshold.

    Data type: Object

    "crossedThresholdInformation":
{
  "direction": "String",
  "granularity": "String",
  "indicatorName": "String",
  "indicatorUnit": "String",
  "observedValue": "String",
  "thresholdCrossingDescription": "String",
  "thresholdId": "String",
  "thresholdRef": "String"
}
    crossedThresholdInformation.direction Threshold crossing direction.
    Valid values:
    • DOWN
    • UP

    Data type: String
    crossedThresholdInformation.granularity Granularity at which the indicator is evaluated for threshold crossing. For example, 5MINUTES.

    Data type: String
    crossedThresholdInformation.indicatorName Name of the indicator that crosses the alarm threshold.

    Data type: String
    crossedThresholdInformation.indicatorUnit Measurement unit of the indicator corresponding to the crossed threshold.

    Data type: String
    crossedThresholdInformation.observedValue Number identifying the indicator crossing the threshold.

    Data type: String
    crossedThresholdInformation.thresholdCrossingDescription More threshold details of the threshold crossing alarm.

    Data type: String
    crossedThresholdInformation.thresholdId Required.
    Unique identifier of the threshold that caused the alarm.

    Data type: String
    crossedThresholdInformation.thresholdRef URL of the threshold object.

    Data type: String
    href URL reference to the alarm.

    Data type: String
    perceivedSeverity Required. Alarm severity.
    Valid values:
    • CLEAR
    • CRITICAL
    • MAJOR
    • MINOR
    • WARNING

    Data type: String
    plannedOutageIndication Indicates that the managed object for this alarm is in a planned outage state. For example, planned maintenance or out-of-service.

    Data type: String
    probableCause Required.
    Most likely situation to trigger the alarm. Use with alarmType to qualify the alarm.

    Data type: String
    proposedRepairActions If available to the system, provides a repair action to resolve the issue that triggers the alarm.

    Data type: String
    serviceAffecting Flag that indicates whether the alarm affects service.
    Valid values:
    • true: Alarm affects service performance or availability.
    • false: Alarm doesn't affect service.

    Default: false

    Data type: Boolean
    specificProblem Specific problem that triggers the alarm. Use with the probableCause tparameter o qualify the alarm.

    Data type: String

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 16. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json.
    Content-Type Data format of the request body. Only supports application/json.
    Table 17. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 18. Status codes
    Status code Description
    201 Successful. The request was successfully processed.
    400 Bad request.

    Possible reasons:

    • Invalid payload. Missing required alarm ID.
    • Invalid payload. Required field missing:<field name>.
    • Invalid payload. Missing required object.
    • Event not created, failed.
    • Unable to clear event.
    • Unable to update event.
    • The event doesn’t exist.

    Response body parameters (JSON)

    Name Description
    alarmChangedTime Date and time the alarm changed in GMT on the alarm-owning system. This value updates when changes to the alarm from the alarmed resource occur or a change from a client update triggers the alarm. This value is required in the response.

    Data type: String
    href URL reference to the alarm.

    Data type: String
    id Unique identifier of the alarm. Value determined by the system owning the alarm.

    Data type: String

    cURL request

    In this example, the severity is reduced to MINOR.

    curl "https://<instance>.service-now.com/api/sn_ind_tmf642/alarm_mgmt/alarm/6e116bb8db09201087b9a8394b961950_<external-alarm-id>" \
--request PATCH \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
     \"href\":\"http://api/alarm/ROUTER_IF@Cisco-0000-0-0-0-0-00-00-0-- Xz0/00@00\",
     \"externalAlarmId\":\"<external-alarm-id>\",
     \"alarmType\":\"QualityOfServiceAlarm\",
     \"type\":\"QualityOfServiceAlarm\",
     \"ackState\":\"acknowledged\",
     \"perceivedSeverity\":\"MINOR\",
     \"probableCause\":\"Threshold crossed\",
     \"specificProblem\":\"Inbound Traffic threshold crossed\",
     \"alarmedObjectType\":\"ROUTER\",
     \"alarmedObject\":{
        \"id\":\"vManage_000000\",
        \"href\":\" http://api/alarmedobject/000000\"
     },
     \"sourceSystemId\":\"SOURCE_SYSTEM_vManage_00000_000_00\",
     \"alarmDetails\":\"Software Failure on SD-WAN Controller vManage_000000\",
     \"alarmEscalation\": false,
     \"state\":\"RAISED\",
     \"alarmChangedTime\":\"2017-08-15T07:04:15.666Z\",
     \"proposedRepairActions\":\"Switch in standby equipment\",
     \"alarmReportingTime\":\"2017-06-15T07:04:15.666Z\",
     \"alarmRaisedTime\":\"2020-09-15T07:04:15.666Z\",
     \"plannedOutageIndication\":\"IN_SERVICE\",
     \"serviceAffecting\":true,
     \"affectedService\":[
        {
           \"id\":\"SD WAN Enterprise Solutions\",
           \"href\":\"http://api/service/vlan_dot0_dot0\"
        },
        {
           \"id\":\"Santa Clara SD WAN Application Service\",
           \"href\":\"http://api/service/vlan_dot0_dot0\"
        }
     ] 
 }" \
--user 'user:'password'

    Response body.

    {
  "result": {
    "alarmChangedTime": "2017-08-15T07:04:15.666Z",
    "id": "6e116bb8db09201087b9a8394b961950_<external-alarm-id>"
  }
}

    Alarm Management Open API – POST /sn_ind_tmf642/alarm_mgmt/alarm

    Creates an alarm record in the Events [em_event] table.

    When the alarm record is created, an ID for the alarm is added in the Message key field.

    An alert record might also be created based on Alert management rules.

    This endpoint writes the response body to the Additional Info field of the event record in the Events [em_event] table.

    URL format

    Default URL: /api/sn_ind_tmf642/alarm_mgmt/alarm

    Supported request parameters

    Table 19. Path parameters
    Name Description
    None
    Table 20. Query parameters
    Name Description
    None
    Table 21. Request body parameters (JSON)
    Name Description
    affectedService List of one or more services affected by the alarm.

    Data type: Array of Objects

    "affectedService":[
  {
    "href": "String",
    "id": "String"
  },
]
    affectedService.href URL reference that provides details of the affected service.

    Data type: String
    affectedService.id Required.
    Identifier of the service affected by the alarm. This value maps to the affected configuration item (CI) on the alert.

    Data type: String
    alarmDetails Additional details about the alarm.

    Data type: String
    alarmedObject Required. Details of the alarm object. 
    "alarmedObject":
{
  "href": "String",
  "id": "String"
}

    Data type: Object
    alarmedObject.id Required. Unique identifier of the alarm object. This value maps to a CI in the system.

    Data type: String
    alarmedObject.href
    URL reference to get the details of the alarm object.

    Data type: String
    alarmedObjectType Type or class of object associated with the event.

    Data type: String
    alarmRaisedTime Date and time at which the alarm occurs at its source.

    Data type: String
    alarmReportingTime Date and time at which the OSS reports its alarm.
    This value might differ from the alarmRaisedTime value. For example, if an element management system (EMS) maintains the alarm list:
    • The alarmRaisedTime is the time of alarm detection by the network element (NE).
    • The alarmReportingTime is the alarm report time of storage in the EMS alarm list.

    Data type: String
    alarmType Required. Alarm category.

    Data type: String
    crossedThresholdInformation Details about the crossed threshold.

    Data type: Object

    "crossedThresholdInformation":
{
  "direction": "String",
  "granularity": "String",
  "indicatorName": "String",
  "indicatorUnit": "String",
  "observedValue": "String",
  "thresholdCrossingDescription": "String",
  "thresholdId": "String",
  "thresholdRef": "String"
}
    crossedThresholdInformation.direction Threshold crossing direction.
    Valid values:
    • DOWN
    • UP

    Data type: String
    crossedThresholdInformation.granularity Granularity at which the indicator is evaluated for threshold crossing. For example, 5MINUTES.

    Data type: String
    crossedThresholdInformation.indicatorName Name of the indicator that crosses the alarm threshold.

    Data type: String
    crossedThresholdInformation.indicatorUnit Measurement unit of the indicator corresponding to the crossed threshold.

    Data type: String
    crossedThresholdInformation.observedValue Number identifying the indicator crossing the threshold.

    Data type: String
    crossedThresholdInformation.thresholdCrossingDescription More threshold details of the threshold crossing alarm.

    Data type: String
    crossedThresholdInformation.thresholdId Required.
    Unique identifier of the threshold that caused the alarm.

    Data type: String
    crossedThresholdInformation.thresholdRef URL of the threshold object.

    Data type: String
    externalAlarmId Required. Unique identifier for the alarm from the source system posting the alarm.

    Data type: String
    id Unique identifier for the system to identify and process the alarm payload as an event.

    This value must be empty if used in the payload. The system generates this unique ID for the event and sends it as part of the response payload.

    Data type: String
    perceivedSeverity Required. Alarm severity.
    Valid values:
    • CLEAR
    • CRITICAL
    • MAJOR
    • MINOR
    • WARNING

    Data type: String
    plannedOutageIndication Indicates that the managed object for this alarm is in a planned outage state. For example, planned maintenance or out-of-service.

    Data type: String
    probableCause Required.
    Most likely situation to trigger the alarm. Use with alarmType to qualify the alarm.

    Data type: String
    proposedRepairActions If available to the system, provides a repair action to resolve the issue that triggers the alarm.

    Data type: String
    serviceAffecting Flag that indicates whether the alarm affects service.
    Valid values:
    • true: Alarm affects service performance or availability.
    • false: Alarm doesn't affect service.

    Default: false

    Data type: Boolean
    sourceSystemId Required. Instance ID of the source alarm.

    Data type: String
    specificProblem Specific problem that triggers the alarm. Use with the probableCause tparameter o qualify the alarm.

    Data type: String
    state Alarm state.
    Valid values:
    • Error
    • Ignored
    • Ready
    • Processed
    If an invalid value is provided, the state is set to Ready.

    If the state is Ready, an alert is created in the Alert [em_alert] table and the state then becomes Processed.

    If the state is Processed, Ignored, or Error no alert is created.

    Default value: Ready

    Data type: String

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 22. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json.
    Content-Type Data format of the request body. Only supports application/json.
    Table 23. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 24. Status codes
    Status code Description
    201 Successful. The request was successfully processed.
    400 Bad request.

    Possible reasons:

    • Invalid payload. Missing required alarm ID.
    • Invalid payload. Required field missing:<field name>.
    • Invalid payload. Missing required object.
    • Event not created, failed.
    • Unable to clear event.
    • Unable to update event.
    • The event doesn’t exist.

    Response body parameters (JSON)

    Name Description
    affectedService List of one or more services affected by the alarm.

    Data type: Array of Objects

    "affectedService":[
  {
    "href": "String",
    "id": "String"
  },
]
    affectedService.href URL reference that provides details of the affected service.

    Data type: String
    affectedService.id Identifier of the service affected by the alarm. This value maps to the affected configuration item (CI) on the alert.

    Data type: String
    alarmDetails Additional details about the alarm.

    Data type: String
    alarmedObject Details of the alarm object. 
    "alarmedObject":
{
  "href": "String",
  "id": "String"
}

    Data type: Object
    alarmedObject.id Unique identifier of the alarm object. This value maps to a CI in the system.

    Data type: String
    alarmedObject.href
    URL reference to get the details of the alarm object.

    Data type: String
    alarmedObjectType Type or class of object associated with the event.

    Data type: String
    alarmRaisedTime Date and time at which the alarm occurs at its source.

    Data type: String
    alarmReportingTime Date and time at which the OSS reports its alarm.
    This value might differ from the alarmRaisedTime value. For example, if an element management system (EMS) maintains the alarm list:
    • The alarmRaisedTime is the time of alarm detection by the network element (NE).
    • The alarmReportingTime is the alarm report time of storage in the EMS alarm list.

    Data type: String
    alarmType Alarm category.

    Data type: String
    crossedThresholdInformation Details about the crossed threshold.

    Data type: Object

    "crossedThresholdInformation":
{
  "direction": "String",
  "granularity": "String",
  "indicatorName": "String",
  "indicatorUnit": "String",
  "observedValue": "String",
  "thresholdCrossingDescription": "String",
  "thresholdId": "String",
  "thresholdRef": "String"
}
    crossedThresholdInformation.direction Threshold crossing direction.
    Valid values:
    • DOWN
    • UP

    Data type: String
    crossedThresholdInformation.granularity Granularity at which the indicator is evaluated for threshold crossing. For example, 5MINUTES.

    Data type: String
    crossedThresholdInformation.indicatorName Name of the indicator that crosses the alarm threshold.

    Data type: String
    crossedThresholdInformation.indicatorUnit Measurement unit of the indicator corresponding to the crossed threshold.

    Data type: String
    crossedThresholdInformation.observedValue Number identifying the indicator crossing the threshold.

    Data type: String
    crossedThresholdInformation.thresholdCrossingDescription More threshold details of the threshold crossing alarm.

    Data type: String
    crossedThresholdInformation.thresholdId Unique identifier of the threshold that caused the alarm.

    Data type: String
    crossedThresholdInformation.thresholdRef URL of the threshold object.

    Data type: String
    externalAlarmId Unique identifier for the alarm from the source system posting the alarm.

    Data type: String
    href URL of the resource.

    Data type: String
    id Unique identifier for the system to identify and process the alarm payload as an event.

    Data type: String
    perceivedSeverity Alarm severity.
    Valid values:
    • CLEAR
    • CRITICAL
    • MAJOR
    • MINOR
    • WARNING

    Data type: String
    plannedOutageIndication Indicates that the managed object for this alarm is in a planned outage state. For example, planned maintenance or out-of-service.

    Data type: String
    probableCause Most likely situation to trigger the alarm. Use with alarmType to qualify the alarm.

    Data type: String
    proposedRepairActions If available to the system, provides a repair action to resolve the issue that triggers the alarm.

    Data type: String
    serviceAffecting Flag that indicates whether the alarm affects service.
    Valid values:
    • true: Alarm affects service performance or availability.
    • false: Alarm doesn't affect service.

    Default: false

    Data type: Boolean
    sourceSystemId Instance ID of the source alarm.

    Data type: String
    specificProblem Specific problem that triggers the alarm. Use with the probableCause tparameter o qualify the alarm.

    Data type: String
    state Alarm state.
    Valid values:
    • Error
    • Ignored
    • Ready
    • Processed
    If an invalid value is provided, the state is set to Ready.

    If the state is Ready, an alert is created in the Alert [em_alert] table and the state then becomes Processed.

    If the state is Processed, Ignored, or Error no alert is created.

    Default value: Ready

    Data type: String

    cURL request

    This example creates an alarm.

    curl "https://<instance>.service-now.com/api/sn_ind_tmf642/alarm_mgmt/alarm" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
     "href":"http://api/alarm/ROUTER_IF@Cisco-0000-0-0-0-0-00-00-0-- Xz0/00@00",
     "externalAlarmId":"<external-alarm-id>",
     "alarmType":"QualityOfServiceAlarm",
     "type":"QualityOfServiceAlarm",
     "ackState":"acknowledged",
     "perceivedSeverity":"CRITICAL",
     "probableCause":"Threshold crossed",
     "specificProblem":"Inbound Traffic threshold crossed",
     "alarmedObjectType":"ROUTER",
     "alarmedObject":{
        "id":"vManage_000000",
        "href":" http://api/alarmedobject/000000"
     },
     "sourceSystemId":"SOURCE_SYSTEM_vManage_00000_000_00",
     "alarmDetails":"Software Failure on SD-WAN Controller vManage_000000",
     "state":"RAISED",
     "alarmChangedTime":"2017-08-15T07:04:15.666Z",
     "proposedRepairActions":"Switch in standby equipment",
     "alarmReportingTime":"2017-06-15T07:04:15.666Z",
     "alarmRaisedTime":"2020-09-15T07:04:15.666Z",
     "plannedOutageIndication":"IN_SERVICE",
     "serviceAffecting":true,
     "affectedService":[
        {
           "id":"SD WAN Enterprise Solutions",
           "href":"http://api/service/vlan_dot0_dot0"
        },
        {
           "id":"Santa Clara SD WAN Application Service",
           "href":"http://api/service/vlan_dot0_dot0"
        }
     ] 
 }" \
--user 'user':'password'

    Response body.

    {
     "href":"http://api/alarm/ROUTER_IF@Cisco-0000-0-0-0-0-00-00-0-- Xz0/00@00",
     "externalAlarmId":"<external-alarm-id>",
     "alarmType":"QualityOfServiceAlarm",
     "type":"QualityOfServiceAlarm",
     "ackState":"acknowledged",
     "perceivedSeverity":"CRITICAL",
     "probableCause":"Threshold crossed",
     "specificProblem":"Inbound Traffic threshold crossed",
     "alarmedObjectType":"ROUTER",
     "alarmedObject":{
        "id":"vManage_000000",
        "href":" http://api/alarmedobject/000000"
     },
     "sourceSystemId":"SOURCE_SYSTEM_vManage_00000_000_00",
     "alarmDetails":"Software Failure on SD-WAN Controller vManage_000000",
     "state":"RAISED",
     "alarmChangedTime":"2017-08-15T07:04:15.666Z",
     "proposedRepairActions":"Switch in standby equipment",
     "alarmReportingTime":"2017-06-15T07:04:15.666Z",
     "alarmRaisedTime":"2020-09-15T07:04:15.666Z",
     "plannedOutageIndication":"IN_SERVICE",
     "serviceAffecting":true,
     "affectedService":[
        {
           "id":"SD WAN Enterprise Solutions",
           "href":"http://api/service/vlan_dot0_dot0"
        },
        {
           "id":"Santa Clara SD WAN Application Service",
           "href":"http://api/service/vlan_dot0_dot0"
        }
     ] 
 }

    Alarm Management Open API – POST /sn_ind_tmf642/alarm_mgmt/alarm/{id}/clear

    Clears a specified alarm and closes any associated alert.

    URL format

    Default URL: /api/sn_ind_tmf642/alarm_mgmt/alarm/{id}/clear

    Supported request parameters

    Table 25. Path parameters
    Name Description
    id Unique identifier of the alarm to clear.

    Data type: String

    Table: In the Message key field of the Events [em_events] table.
    Table 26. Query parameters
    Name Description
    None
    Table 27. Request body parameters (JSON)
    Name Description
    alarmClearedTime Date and time at which the alarm clears at the source.

    Data type: String

    Table: In the Time of event field of the Events [em_events] table.
    clearSystemId Required. Name of the instance from which the alarmCleared operation was invoked.

    Data type: String
    clearUserId Required. Unique ID of the user who invoked the alarmCleared operation.

    Data type: String

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 28. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json.
    Content-Type Data format of the request body. Only supports application/json.
    Table 29. Response headers
    Name Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 30. Status codes
    Status code Description
    201 Successful. The request was successfully processed.
    400 Bad request.

    Possible reasons:

    • Invalid payload. Missing required alarm ID.
    • Invalid payload. Required field missing:<field name>.
    • Invalid payload. Missing required object.
    • Event not created, failed.
    • Unable to clear event.
    • Unable to update event.
    • The event doesn’t exist.

    Response body parameters (JSON)

    Name Description
    alarmClearedTime Date and time at which the alarm clears at the source.

    Data type: String

    Table: In the Time of event field of the Events [em_events] table.
    clearSystemId Name of the instance from which the alarmCleared operation was invoked.

    Data type: String
    clearUserId Unique ID of the user who invoked the alarmCleared operation.

    Data type: String
    href URL of the alarm.

    Data type: String
    id Unique ID.

    Data type: String

    Table: In the Message key field of the record in the Events [em_events] table.

    cURL request

    This example clears an alarm.

    curl "https://<instance>.service-now.com/api/sn_ind_tmf642/alarm_mgmt/alarm/6e116bb8db09201087b9a8394b961950_<external-alarm-id>/clear" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"alarmClearedTime\": \"2017-08-15 06:04:15\",
  \"clearSystemId\": \"<source_instance_name>\",
  \"clearUserId\": \"SOURCE_SYSTEM_vManage_00000_000_00\" 
}" \
--user 'user':'password'

    Response body.

    {
  "result": {
    "alarmClearedTime": "2017-08-15 06:04:15",
    "clearSystemId": "<source_instance_name>",
    "clearUserId": "SOURCE_SYSTEM_vManage_00000_000_00",
    "id": "6e116bb8db09201087b9a8394b961950_<external-alarm-id>"
  }
}