This Fault Management RESTCONF API tutorial documents a new API method introduced in NSP 24.4, that allows external users to create alarms in the NSP FM system.
Typically, as is the case with most other POST requests, the new method will require a basic list of mandatory alarm values to be included. These are defined in the body of the RESTCONF POST request. The purpose of the tutorial is to explain the implementation of the new method, and the allowable values that may be defined in the specific alarm properties.
Externally created alarms generated through this method will be visible in the NSP FM GUI application , assuming the request is successful.
Actions applicable to externally created alarms are equally relevant as they are for internally generated NSP alarms, for example, alarm acknowledgment, severity change, alarm deletion .. etc. Externally created alarms will also be sent as notifications ( of type alarm-create ) via the Kafka NSP-FAULT-YANG notification topic ( also NSP-FAULT )
Example request/responses are also included with a postman collection.
The alarm creation method uses the following POST request:
POST https://{{server}}:8545/restconf/data/nsp-fault:alarms/alarm-list
The following example demonstrates the mandatory properties, and are provided as a working example, the values specified in the body of the request :
Body
{
"nsp-fault:alarm" : [
{
"perceived-severity": "warning",
"alarm-type-qualifier": "TestTaskOverload",
"probable-cause-string": "outOfCPUCycles",
"alarm-type-id": "communicationsAlarm",
"resource": "fdn:app:external:test-md-node2:default",
"affected-object-type": "ExternalSystem",
"affected-object-name": "test-md-node2",
"alt-resource": "test-md-node2:default/TestTaskOverload"
}
]
}As is usual for NSP RESTCONF API queries, the request requires a valid authentication token specified in the header of the request.
The above example is for an alarming object resource "test-md-node2:default". This is not an alarming object managed natively by NSP. This is a perfectly valid use case of this API method. With this method, it is not mandatory that the object exists within the NSP model for an alarm to be created.
It is intended as part of this API design, that externally created alarms may be implementing their own proprietary alarm definitions. For example, externally created alarms can specify their own object resource naming convention. Provided that the necessary syntax rules ( see Input Properties table below ) are followed, these fields can represent alarming objects ( the resource ) unknown to NSP. This also applies to alarm names ( the alarm-type-qualifier ), they do not have to align with values used in NSP's internally managed alarm definitions. In other words, both these properties can be used to allow modelling of alarming object entities outside of the NSP model.
The probable-cause-string value, alarm-type-id and perceived-severity are strict values, and need to align to the NSP alarm modelling guidelines.
These values are defined in the RESTCONF FM nsp-fault.yang module ( fault-management.zip. ) published on the NSP developer portal API documentation page, see the following link for more information: https://network.developer.nokia.com/api-documentation
Note: alarms created externally in the RESTCONF FM API will be visible in the NSP FM GUI, the RESTCONF FM NSP-FAULT-YANG Kafka topic , and also the REST FM NSP-FAULT Kafka topic . This method has the potential to impact clients/vendor notifications inadvertently, any user generated alarms injected into the system needs to consider this fact.
Externally created alarms require the source-system to be specified as "fdn:app:external". When the source-system is not specified, the alarm source-system value will be populated as "fdn:app:external". For any NBI clients not wishing to process such data, a possible approach is to suppress this source-system value in the Kafka consumer property filter.
It is highly recommended that the alt-resource ( the alarm object full name ) is unique, otherwise an exception is returned during the alarm creation attempt, if for example, a second attempt was performed to send the same request without modification of the alt-resource value, this would trigger the exception during validation of the request.
Externally raised alarms created through this API, when successful, will return a 201 response code.
The alarm object created isn't sent as part of the 201 response.
Note: whilst response 201 normally indicates a successful operation, if alarm squelching is enabled, the alarm will not be raised in the NSP FM application. The NSP-FAULT-YANG Kafka consumer can be used to verify successful creation.
The generic RESTCONF POST nsp-inventory:find method can also be used to retrieve an externally created alarm object by specifying the alt-resource property ( the alarm object full name ) in the xpath-filter, for example:
POST https://{{server}}:8545/restconf/operations/nsp-inventory:find
Body
{
"input" : {
"xpath-filter": "/nsp-fault:alarms/alarm-list/alarm[source-system = 'fdn:app:external' and alt-resource='test-md-node2:default/TestTaskOverload']"
}
}The inclusion of the additional source-system is an additional safeguard to ensure that solely the alarm created externally, is received. However, provided the alt-resource is uniquely assigned ( a recommendation for external alarm creation on NSP modelled objects ), it may suffice to only specify the alt-resource in the xpath-filter.
The following example demonstrates a working example for an alarm created against a NSP managed object. All additional properties supported, are specified in this sample.
In this example, the alarm resource is an equipment port object
POST https://{{server}}:8545/restconf/data/nsp-fault:alarms/alarm-list
Body
{
"nsp-fault:alarm" : [
{
"source-type": "nsp",
"source-system": "fdn:app:external",
"perceived-severity": "warning",
"alarm-type-qualifier": "ThresholdMaxAlarmsReached",
"probable-cause-string": "equipmentMalfunction",
"alarm-type-id": "equipmentAlarm",
"additional-text": "External alarm",
"ne-id": "92.168.99.124",
"ne-name": "s168_99_124_acpm",
"resource": "fdn:app:mdm-ami-cmodel:92.168.99.124:equipment:Equipment:/port[port-id='1/1/21']",
"affected-object-type": "equipment.Equipment",
"affected-object-name": "port=1/1/21",
"time-created": "2024-02-26T19:13:40.286Z",
"last-raised": "2024-02-26T19:13:40.286Z",
"implicitly-cleared": false,
"alt-resource": "92.168.99.124:fm:Alarm:/port[port-id='1/1/21']/ThresholdMaxAlarmsReached"
}
]
}In the above sample, the potential for error due to non-unique alt-resource assignment, is solved by appending the unique alarm-type-qualifier ( the alarm name ) after the equipment port identifier.
As a general recommendation, this is a sound approach to ensuring that the alarm object full name ( alt-resource ) will be valid for alarm creation success.
Also in this sample, a port identifier value is utilised to reflect an existing NSP managed equipment port. The externally created alarm will always have the "fdn:app:external" value assigned to the source-system.
This means that if a FM RESTCONF API / FM GUI user wanted to find alarms raised against a specific NSP resource object name, it is possible to just retrieve only the externally created alarms, all alarms, or only NSP internally created alarms, by specifying the source-system value in the xpath-filter.
It is important to note that multiple alarms can exist against a NSP resource object.
An example of a NSP internally created port alarm is included for convenience below:
{
"@": {
"nsp-model:schema-nodeid": "/nsp-fault:alarms/alarm-list/alarm",
"nsp-model:identifier": "/nsp-fault:alarms/alarm-list/alarm[alarm-fdn='fdn:model:fm:Alarm:515257']"
},
"node-time-offset": -1,
"number-of-occurrences-since-clear": 0,
"probable-cause-string": "equipmentMalfunction",
"alarm-type-id": "processingErrorAlarm",
"last-changed": null,
"acknowledged": false,
"cleared-by": "N/A",
"original-severity": "major",
"is-cleared": false,
"was-acknowledged": false,
"admin-state": "unlocked",
"root-cause-resource": [
"fdn:model:fm:Alarm:515257"
],
"ne-id": "92.168.96.17",
"acknowledged-by": "N/A",
"frequency": 0,
"last-time-severity-changed": null,
"last-raised": "2023-10-13T13:59:53.745Z",
"user-text": "N/A",
"ne-name": "mdNodeS",
"source-type": "mdm",
"affected-object-type": "equipment.Equipment",
"time-created": "2023-10-13T13:59:53.745Z",
"source-system": "fdn:app:mdm-ami-cmodel",
"alarm-type-qualifier": "LinkDown",
"impacted-resource": {
"alarmFdn": "fdn:model:fm:Alarm:515257",
"impacts": []
},
"additional-text": "Interface 1/1/c1/8 is not operational",
"last-time-de-escalated": null,
"number-of-occurrences-since-ack": 0,
"resource": "fdn:app:mdm-ami-cmodel:92.168.96.17:equipment:Equipment:/port[port-id='1/1/c1/8']",
"perceived-severity": "major",
"last-time-acknowledged": null,
"number-of-occurrences": 1,
"previous-severity": "indeterminate",
"impact-count": 0,
"alarm-fdn": "fdn:model:fm:Alarm:515257",
"last-time-escalated": null,
"affected-object-name": "port=1/1/c1/8",
"implicitly-cleared": true,
"alt-resource": "92.168.96.17:fm:Alarm:/port[port-id='1/1/c1/8']/linkDown",
"last-time-cleared": null,
"is-root-cause": true
}Note that the source-system in the NSP FM alarm is specified as "fdn:app:mdm-ami-cmodel"
The following sample is the externally created port alarm from above, note the values sent in that request are set, and source-system is specified as "fdn:app:external"
{
"@": {
"nsp-model:schema-nodeid": "/nsp-fault:alarms/alarm-list/alarm",
"nsp-model:identifier": "/nsp-fault:alarms/alarm-list/alarm[alarm-fdn='fdn:model:fm:Alarm:55509']"
},
"node-time-offset": -1,
"number-of-occurrences-since-clear": 0,
"probable-cause-string": "equipmentMalfunction",
"alarm-type-id": "equipmentAlarm",
"last-changed": null,
"acknowledged": false,
"cleared-by": "N/A",
"original-severity": "warning",
"is-cleared": false,
"was-acknowledged": false,
"admin-state": "unknown",
"root-cause-resource": [
"fdn:model:fm:Alarm:55509"
],
"ne-id": "92.168.99.124",
"acknowledged-by": "N/A",
"frequency": 0,
"last-time-severity-changed": null,
"last-raised": "2024-02-26T19:13:40.286Z",
"user-text": "N/A",
"ne-name": "s168_99_124_acpm",
"source-type": "nsp",
"affected-object-type": "equipment.Equipment",
"time-created": "2024-02-26T19:13:40.286Z",
"source-system": "fdn:app:external",
"alarm-type-qualifier": "ThresholdMaxAlarmsReached",
"impacted-resource": {
"alarmFdn": "fdn:model:fm:Alarm:55509",
"impacts": []
},
"additional-text": "External alarm",
"last-time-de-escalated": null,
"number-of-occurrences-since-ack": 0,
"resource": "fdn:app:mdm-ami-cmodel:92.168.99.124:equipment:Equipment:/port[port-id='1/1/21']",
"perceived-severity": "warning",
"last-time-acknowledged": null,
"number-of-occurrences": 1,
"previous-severity": "indeterminate",
"impact-count": 0,
"alarm-fdn": "fdn:model:fm:Alarm:55509",
"last-time-escalated": null,
"affected-object-name": "port=1/1/21",
"implicitly-cleared": false,
"alt-resource": "92.168.99.124:fm:Alarm:/port[port-id='1/1/21']/ThresholdMaxAlarmsReached",
"last-time-cleared": null,
"is-root-cause": true
}The external alarm create API method allows the affected-object-type to be loosely defined, and this may be useful for alarms for external systems, unknown to NSP.
However, when raising alarms against objects that exist in the NSP model, it is recommended to align the affected-object-type value also.
In the previous example, the value was specified to match the existing object class, for a port that is defined as equipment.Equipment. This is a highly recommended approach to be followed when creating alarms externally, against NSP modeled objects.
The RESTCONF method nsp-inventory:find-by-source is useful for retrieving alarming objects modelled in NSP, using properties available in the RESTCONF FM alarm
The following find-by-source request uses information from the previous alarm. It requires two inputs, the schema-nodeid value ( affected-object-type ) and the sources value ( resource )
POST https://server:8545/restconf/operations/nsp-inventory:find-by-source
Body
{
"input" :
{ "schema-nodeid": "equipment.Equipment", "sources" : ["fdn:app:mdm-ami-cmodel:92.168.96.17:equipment:Equipment:/port[port-id='1/1/c1/8']"] }
}The request is not necessarily intended to be part of any flow for external alarm creation. It is only being referenced here to assist in the understanding of the data source of these values.
When raising the alarm against a NSP object, the affected-object-type should align with the nsp-model:schema-nodeid value modelled as per the nsp-inventory:output
For the following objects, the short naming convention is needed in order for the underlying user privileges that are based on user access control ( UAC ) to be applied properly:
For NE object, use equipment.NetworkElement
For port, use equipment.Equipment
For services, physical /optical links, LSP, GRE , LSP tunnels, use service.Service
For service sites, use service.Site
For SAPs ( service access points ), use service.Endpoint
For service resource binding objects, use service.ServiceResourceBinding
It is important to ensure that the naming specified in the affected-object-type of an externally created alarm, raised against existing NSP modeled objects, is using the correct classes. The underlying user privileges that are based on user access control ( UAC ) are reliant on those classes, otherwise, non-admin users may not be able to view the externally created alarms
For alarms that are raised on objects that don't exist in NSP, the affected-object-type should not begin with '/' nor contain any period
Table - Input Properties
| Property |
|
|
|
| source-type |
|
|
|
| source-system |
|
|
|
| perceived-severity |
|
|
|
| alarm-type-qualifier |
|
|
string length up to 4096 |
| probable-cause-string |
|
|
|
| alarm-type-id |
|
|
|
| additional-text |
|
|
|
| ne-id |
|
|
|
| ne-name |
|
|
|
| resource |
|
|
|
| affected-object-type |
|
|
|
| affected-object-name |
|
|
|
| time-created |
|
|
|
| last-raised |
|
|
|
| implicitly-cleared |
|
|
|
| alt-resource |
|
|
|
Timestamp fields, last-raised and time-created must use ISO8601 format. These would need to be converted if the external alarm timestamp values were in another format ( eg: epoch etc )
The implicitly-cleared property cannot be set to true, if specified in the request. This means that alarms created externally will remain in the NSP FM alarms list. They will either need to be deleted using an API request, or from within the FM application. Alarm policies will be created within NSP FM for externally created alarms, and they can also be aged/expired like any other internally created alarm.
Please see the attached postman collection, with sample requests/responses.
It should be understood the importance of ensuring consistent alarm definitions when raising alarms against resource objects used in the NSP model. These externally created alarms will co-exist with alarms from other source types, and may be visible to other FM users. For consistency of implementation, it is recommended that external alarm API users become familiar with the sample responses available in the FM RESTCONF API postman collections. The FM REST API postman collections may also be useful.
Creating large amounts of alarms through this API may impact performance. Nokia Product Line Management has determined that this alarm rate should exceed no more than 5 alarms per hour ( sustained )
FM external alarm creation users can also refer to the inventory tutorials section of the NSP developer portal for more information about the NSP model.