TM Forum Specification

Alarm Management
API REST Specification

TMF642
Release 17.0.1
December 2017

Latest Update: TM Forum Release 17.0 TM Forum Approved

Version 1.0.1 IPR Mode: RAND

TM Forum 2017. All Rights Reserved.

Alarm Management REST API Specification

NOTICE
Copyright © TM Forum 2017. All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that
comment on or otherwise explain it or assist in its implementation may be prepared, copied, published,
and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice
and this section are included on all such copies and derivative works. However, this document itself may
not be modified in any way, including by removing the copyright notice or references to TM FORUM,
except as needed for the purpose of developing any document or deliverable produced by a TM FORUM
Collaboration Project Team (in which case the rules applicable to copyrights, as set forth in the TM
FORUM IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by TM FORUM or its
successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and TM FORUM
DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY
OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE.

TM FORUM invites any TM FORUM Member or any other party that believes it has patent claims that
would necessarily be infringed by implementations of this TM Forum Standards Final Deliverable, to notify
the TM FORUM Team Administrator and provide an indication of its willingness to grant patent licenses to
such patent claims in a manner consistent with the IPR Mode of the TM FORUM Collaboration Project
Team that produced this deliverable.

The TM FORUM invites any party to contact the TM FORUM Team Administrator if it is aware of a claim
of ownership of any patent claims that would necessarily be infringed by implementations of this TM
FORUM Standards Final Deliverable by a patent holder that is not willing to provide a license to such
patent claims in a manner consistent with the IPR Mode of the TM FORUM Collaboration Project Team
that produced this TM FORUM Standards Final Deliverable. TM FORUM may include such claims on its
website, but disclaims any obligation to do so.

TM FORUM takes no position regarding the validity or scope of any intellectual property or other rights
that might be claimed to pertain to the implementation or use of the technology described in this TM
FORUM Standards Final Deliverable or the extent to which any license under such rights might or might
not be available; neither does it represent that it has made any effort to identify any such rights.
Information on TM FORUM's procedures with respect to rights in any document or deliverable produced
by a TM FORUM Collaboration Project Team can be found on the TM FORUM website. Copies of claims
of rights made available for publication and any assurances of licenses to be made available, or the result
of an attempt made to obtain a general license or permission for the use of such proprietary rights by
implementers or users of this TM FORUM Standards Final Deliverable, can be obtained from the TM
FORUM Team Administrator. TM FORUM makes no representation that any information or list of
intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential
Claims.

© TM Forum 2017. All Rights Reserved. Page 2

Alarm Management REST API Specification

Direct inquiries to the TM Forum office:

4 Century Drive, Suite 100

Parsippany, NJ 07054 USA
Tel No. +1 973 944 5100
Fax No. +1 973 944 5110
TM Forum Web Page: www.tmforum.org

© TM Forum 2017. All Rights Reserved. Page 3

Alarm Management REST API Specification

TABLE OF CONTENTS
NOTICE........................................................................................................................................................................... 2

Table of Contents ............................................................................................................................................................ 4

List of Tables ................................................................................................................................................................... 6

Introduction ..................................................................................................................................................................... 7

SAMPLE USE CASES .................................................................................................................................................... 8

Sample Use Case – Simple Alarm Forwarding .......................................................................................................... 8

Sample Use Case – OSS-to-OSS .............................................................................................................................. 9

RESOURCE MODEL .................................................................................................................................................... 11

Managed Entity and Task Resource Models ............................................................................................................ 11

ALARM .................................................................................................................................................................. 11

alarmCreate Notification ........................................................................................................................................... 18

alarmCleared Notification.......................................................................................................................................... 20

alarmAckState Notification ........................................................................................................................................ 21

alarmChange Notification.......................................................................................................................................... 22

API OPERATION TEMPLATES ................................................................................................................................... 25

POST /API/alarm ...................................................................................................................................................... 27

PATCH /API/alarm/{alarmId}..................................................................................................................................... 32

POST /API/alarm/{alarmId}/Clear ............................................................................................................................. 36

GET /API/alarm/{alarmId} ......................................................................................................................................... 37

GET /API/alarms ....................................................................................................................................................... 41

POST /API/ackAlarms............................................................................................................................................... 42

POST /API/unAckAlarms .......................................................................................................................................... 45

POST /API/clearAlarms ............................................................................................................................................ 48

POST /API/commentAlarms ..................................................................................................................................... 51

POST /API/groupAlarms ........................................................................................................................................... 53

POST /API/ungroupAlarms ....................................................................................................................................... 56

API NOTIFICATIOn TEMPLATES ................................................................................................................................ 60

REGISTER LISTENER POST /hub .......................................................................................................................... 60

© TM Forum 2017. All Rights Reserved. Page 4

Alarm Management REST API Specification

UNREGISTER LISTENER DELETE hub/{id} ........................................................................................................... 60

publish {EventTYPE} POST /listener ........................................................................................................................ 61

Release History ......................................................................................................................................................... 63

© TM Forum 2017. All Rights Reserved. Page 5

Alarm Management REST API Specification

LIST OF TABLES

Figure 1 – Alarm resource model 16

Figure 2 - Alarm API Data Model 17

© TM Forum 2017. All Rights Reserved. Page 6

Alarm Management REST API Specification

INTRODUCTION

The TM Forum Alarm Management API applies lessons that were learned in previous generations of similar APIs
that were implemented in the Telecommunication industry, starting from ITU recommendations, TM Forum OSS/J,
MTOSI and TIP interfaces, NGMN alignment initiative between 3GPP and TM Forum interfaces, and the more recent
ETSI work on requirements for NFV interfaces.

This document defines the REST API for Alarm Management. The API does not assume a particular management
layer, so the monitored objects can be either Resource, Service or Customer layer.

There is a strong desire from Service Providers to provide a Fault Management interface that can be used in a
simple way to do simple alarm reporting while also covering more complex OSS-to-OSS scenarios. The Alarm
Management interface should support both and should not add complexity when used in the context of simple Alarm
Reporting.

© TM Forum 2017. All Rights Reserved. Page 7

Alarm Management REST API Specification

SAMPLE USE CASES

The Alarm Management API provides the standardized client interface to Alarm Management systems for creating,
tracking and managing alarms among partners. The interface supports alarm management on both resources and
services. The alarmed objects are not restricted to any particular technology or a vendor, so the API can be used in a
wide variety of fault management cases.

In real-life deployments we see various levels of fault management API needs starting from simple subscription on
alarm lifecycle events, up to full synchronization of acknowledgements and root cause analysis between two alarm
management systems.

Two main kinds of business scenarios were identified:

• Management Functions subscriptions ("simple" alarm notifications)

• Synchronization of Management systems (on alarm events, threshod crossing alarms, acknowledgements,
root cause analysis, etc.)

Sample Use Case – Simple Alarm Forwarding

In the first case, one party of the interface is an Alarm Management system (the alarm-owning system) and the
second party is a management function that is subscribed on events, mainly alarm life-cycle events. It cannot be
assumed that the subscribed function has a persistent view of the alarms, as it is not necessarily an alarm
management system. The subscriber party can be a UI, a communication hub, a Service Quality management
system, a BSS system, or any other function that is interested in alarm events. In this case, the operations that will
be used are typically:

• Alarm life-cycle notificatoins: Raise notification (mandatory), Clear notification(mandatory), Change

notification (optional)
• Get Alarms operations used by the Management Function to get synchronized on the state of active alarms
in situatuations where snapshots of the active alarms are required, such as system start, or recovery from
communication failures. This operation may include a filter on the subset of alarms that are of interest.
• The acknowledgement notification (optional)

© TM Forum 2017. All Rights Reserved. Page 8

Alarm Management REST API Specification

Sample Use Case – OSS-to-OSS

The second case is where the two parties are both alarm management systems/functions and they have to
synchronize alarms in different aspects. Typically Alarm Management system A is one of the alarm data sources of
Alarm management system Z. In this case the operations will be slightly different with a tighter integration:

• Alarm management system A can raise, change and clear alarms in Alarm Managment system Z
• Alarm management system A can acknowledge alarms in Alarm Managment system Z
• Alarm Management system A can apply root cause analysis results in Alarm Management system Z by using
the Group and Ungroup operations.
• Alarm management system A can comment (annotate) alarms in Alarm Managment system Z
• Get Alarms operations used by the Management Function to get synchronized on the state of active alarms
in situatuations where snapshots of the active alarms are required, such as system start, or recovery from
communication failures. This operation may include a filter on the subset of alarms that are of interest.

In this scenario, since the level of integration is tighter, it is important that AlarmManagement System A gets the
information on the success of the oiperations in Alarm management system Z.

© TM Forum 2017. All Rights Reserved. Page 9

Alarm Management REST API Specification

© TM Forum 2017. All Rights Reserved. Page 10

Alarm Management REST API Specification

RESOURCE MODEL

Managed Entity and Task Resource Models

ALARM

Example of the JSON representation of the ALARM

"id:": "ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"href": " http://api/alarm/"ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"externalAlarmId": "cisco-7609-1937465789",

"alarmType": "QualityOfServiceAlarm",

"perceivedSeverity": "CRITICAL",

"probableCause": "Threshold crossed",

"specificProblem": "Inbound Traffic threshold crossed",

"alarmedObjectType": "ROUTER",

"alarmedObject": {

"id": "210875",

"href": " http://api/alarmedobject/210875"

"SourceSystemId": "SYSTEM1",

"alarmDetails": "Threshold on primary counter: Inbound Traffic (Mbits) of

ROUTER_IF at resolution of 5 Minutes",

"alarmState": "RAISED",

"alarmRaisedTime": "2017-06-15T07:04:15.665Z",

"alarmChangedTime": "2017-06-15T07:04:15.666Z",

"alarmClearedTime": "",

"proposedRepairActions": "Switch in standby equipment",

"alarmReportingTime": "2017-06-15T07:04:15.666Z",

© TM Forum 2017. All Rights Reserved. Page 11

Alarm Management REST API Specification

"ackState": "ACKNOWLEDGED",

"ackTime": "2017-06-15T07:04:19.666Z",

"ackUserId": "JOHN DOE",

"ackSystemId": "OSS",

"clearUserId": "",

"clearSystemId": "",

"plannedOutageIndication": "IN_SERVICE",

"alarmEscalation": 0,

"serviceAffecting": true,

"affectedService": [

"id": "Vlan_dot1_dot2",

"href": "http://api/service/Vlan_dot1_dot2"

],

"isRootCause": true,

"correlatedAlarm": [

"id": "Service_ Vlan_dot1_dot2_19",

"href": "http://api/alarm/ Service_ Vlan_dot1_dot2_19"

],

"parentAlarm": [

"id": "",

"href": ""

],

"crossedThresholdInformation": {

"thresholdId": "Router IF_Inbount Traffic_001",

© TM Forum 2017. All Rights Reserved. Page 12

Alarm Management REST API Specification

"thresholdRef": " http://api/threhold/Router IF_Inbount_Traffic_001",

"indicatorName": " IF_IN_MEGABITS ",

"observedValue": " 0.105",

"indicatorUnit": " MEGABITS",

"granularity": "5MINUTES",

"direction": "UP",

"thresholdCrossingDescription": "Threshold on primary counter: Inbound

Traffic (Mbits) of ROUTER_IF"

},

"comments": [

"userId": "Jane Doe",

"time": "2017-06-15T07:04:20.666Z",

"systemId": "OSS_001",

"comment": "Problem reported to system engineering department"

Fields Description

The ALARM fields are described below.

Field M/O Description SID

id M Identifier of the alarm, Y
determined by the alarm
owning system.
Href M A reference to the alarm. N
externalAlarmId O An identifier of the alarm in Y
the source system.
alarmType M Categorize the alarm. Y
perceivedSeverity M Lists the possible severities Y
that can be allocated to an
Alarm.
The values are consistent
with ITU-T Recommendation

© TM Forum 2017. All Rights Reserved. Page 13

Alarm Management REST API Specification

X.733. Once an alarm has

been cleared, its perceived
severity is set to Cleared and
can no longer be set.
probableCause M Further qualifies the alarm in Y
complement of the
alarmType.
specificProblem O Further qualifies the alarm in Y
addition to the
probableCause.
This attribute is defined as a
string. Values are defined by
vendors.
alarmedObjectType O The type (class) of the object Y
associated with the event.
alarmedObject M Y
id M The identifier of the object Y
associated with the event.
Href O A reference to the alarm N
sourceSystemId M Y
alarmDetails O Contains further information Y
on the alarm.
State M Defines the alarm state N
during its life cycle: RAISED,
UPDATED or CLEARED
alarmRaisedTime M Indicates the time (as a date Y
+ time) at which the alarm
occurred at its source.
alarmChangedTime O Indicates the last date and N
time when the alarm is
changed on the alarm-owning
system. Any change to the
alarm whether
coming from the alarmed
resource, or triggered by a
change from the client is
changing this time.
alarmClearedTime O Indicates the time (as a date Y
+ time) at which the alarm is
cleared at the source.
proposedRepairActions O Indicates proposed repair Y
actions, if known to the
system emitting the alarm.
alarmReportingTime O Indicates the time (as a date Y
+ time) at which the alarm
was reported by the owning
OSS. It might be different
from the alarmRaisedTime.
For instance, if the alarm list
is maintained by an EMS, the
alarmRaisedtime would be
the time the alarm
was detected by the NE,
while the
alarmReportingTime would
be the time this alarm was
stored in the alarm list of the
EMS.

© TM Forum 2017. All Rights Reserved. Page 14

Alarm Management REST API Specification

ackState O Provides the Y

Acknowledgement State of
the alarm:
ACKNOWLEDGED,
UNACKNOWLEDGED
ackTime O Provides the time when the Y
alarm has been last
acknowledged or
unacknowledged.
ackUserId O Provides the id of the user Y
who has last changed the ack
state of the alarm, i.e.
acknowledged or
unacknowledged the alarm.
ackSystemId O Provides the name of the Y
system that last changed the
ackState of an alarm, i.e.
acknowledged or
unacknowledged the alarm.
clearUserId O Provides the id of the user Y
who invoked the
alarmCleared operation.
clearSystemId O Provides the id of the system Y
where the user who invoked
the alarmCleared operation is
located.
plannedOutageIndication O Indicates that the Managed Y
Object (related to this alarm)
is in planned outage (in
planned maintenance, or out-
of-service).
alarmEscalation O Indicates if this alarm has Y
been escalated or not.
serviceAffecting O Indicates whether the alarm Y
affects service or not.
affectedService O N
Id M Provides the identifier of the Y
service affected by the alarm.
Href O N
isRootCause O Indicates whether the alarm Y
is a root cause alarm.
correlatedAlarm O Indicates the alarms attached Y
to this alarm as correlated
alarms from a correlation
point of view.
An alarm can be correlated to
one or more underlying
alarms. There might be
multiple levels of alarm
correlation and an underlying
alarm in one relation can be
itself a parent alarm for other
underlying alarms.
Id M Provides the identifier of the Y
correlated underlying alarm
of this alarm.
Href O N

© TM Forum 2017. All Rights Reserved. Page 15

Alarm Management REST API Specification

parentAlarm O Indicates the alarms attached Y

to this alarm as parent alarms
from a correlation point of
view.
Id M Provides the identifier of the Y
parent alarm this alarm.
Href O N
crossedThresholdInformation Identifies the details of the Y
threshold that has been
crossed.
thresholdId M Indicates the threshold id that Y
caused the alarm.
thresholdRef O N
indicatorName O Indicates the name of Y
indicator which crossed the
threshold.
observedValue O Indicates the value of the Y
indicator which crossed the
threshold.
indicatorUnit O Indicates the unit of the Y
measurement of the indicator
corresponding to the
threshold that has been
crossed.
granularity O Indicates the granularity at Y
which the indicator is
evaluated for threshold
crossing.
direction O Indicates the threshold Y
crossing direction: up or
down.
thresholdCrossingDescription O Indicates further information Y
on the threshold crossing
alarm.
Comments O Indicates the comments Y
entered on the alarm.
userId M Indicates the user Y
commenting the alarm.
time M Indicates the time Y
commenting the alarm.
systemId O Indicates the system identifier Y
on which the client set the
comment.
comment M Indicates the text of the Y
comment.

Figure 1 – Alarm resource model

© TM Forum 2017. All Rights Reserved. Page 16

Alarm Management REST API Specification

The diagram below provides a more detailed view of the API data model.

Figure 2 - Alarm API Data Model

The main data entity is naturally the Alarm. It may have the following associations:

• An Alarm may have a parent alarm as a result of root cause analysis

• An alarm may have correlated alarms (descendent alarms) by root cause analysis
• An Alarm may have impacted services
• An alarm may be associated to an Indicator (a measurement) when it is a cross threshold alarm
• An Alarm may be associated to mulriple comments

© TM Forum 2017. All Rights Reserved. Page 17

Alarm Management REST API Specification

ALARMCREATE NOTIFICATION

Example of the JSON representation of alarmCreate Notification:

POST /client/listener

Accept: application/json

"eventType": "AlarmCreateNotification",

"eventTime": "2017-09-27T05:46:25.0Z",

"eventId": "1562233",

"event":

"alarm":

"id:": "ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"href": "http://api/alarm/ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--
Gi9/20@42",

"externalAlarmId": "cisco-7609-1937465789",

"alarmType": "QualityOfServiceAlarm",

"perceivedSeverity": "CRITICAL",

"probableCause": "Threshold crossed",

"specificProblem": "Inbound Traffic threshold crossed",

"alarmedObjectType": "ROUTER",

"alarmedObject": {

"id": "210875",

"href": " http://api/alarmedobject/210875"

"SourceSystemId": "SYSTEM1",

"alarmDetails": "Threshold on primary counter: Inbound Traffic (Mbits) of

ROUTER_IF at resolution of 5 Minutes",

"alarmState": "RAISED",

© TM Forum 2017. All Rights Reserved. Page 18

Alarm Management REST API Specification

"alarmRaisedTime": "2017-06-15T07:04:15.665Z",

"proposedRepairActions": "Switch in standby equipment",

"alarmReportingTime": "2017-06-15T07:04:15.666Z",

"plannedOutageIndication": "IN_SERVICE",

"serviceAffecting": true,

"affectedService": [

"id": "Vlan_dot1_dot2",

"href": "http://api/service/Vlan_dot1_dot2"

],

"crossedThresholdInformation": {

"thresholdId": "Router IF_Inbount Traffic_001",

"thresholdRef": "string",

"indicatorName": " IF_IN_MEGABITS ",

"observedValue": " 0.105",

"indicatorUnit": "MEGABITS",

"granularity": "5MINUTES",

"direction": "UP",

"thresholdCrossingDescription": "Threshold on primary counter: Inbound

Traffic (Mbits) of ROUTER_IF"

© TM Forum 2017. All Rights Reserved. Page 19

Alarm Management REST API Specification

ALARMCLEARED NOTIFICATION

Example of the JSON representation of alarmCleared Notification:

POST /client/listener

Accept: application/json

"eventType": "AlarmClearedNotification",

"eventTime": "2017-09-27T05:48:29.0Z",

"eventId": "1562233",

"event":

"alarm":

"id:": "ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"href": "http://api/alarm/ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--
Gi9/20@42",

"alarmClearedTime": "2017-06-15T07:05:12.666Z ",

"clearUserId": "JOHN DOE",

"clearSystemId": "OSS_01",

© TM Forum 2017. All Rights Reserved. Page 20

Alarm Management REST API Specification

ALARMACKSTATE NOTIFICATION

Example of the JSON representation of alarmAckState Notification:

POST /client/listener

Accept: application/json

"eventType": "AlarmAckStatedNotification",

"eventTime": "2017-09-27T05:48:29.0Z",

"eventId": "1562233",

"event":

"alarm":

"id:": "ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"href": "http://api/alarm/ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--
Gi9/20@42",

"ackState": "ACKNOWLEDGED",

"ackTime": "2017-06-15T07:04:19.666Z",

"ackUserId": "JOHN DOE",

"ackSystemId": "OSS"

}
}
}

© TM Forum 2017. All Rights Reserved. Page 21

Alarm Management REST API Specification

ALARMCHANGE NOTIFICATION

Example of the JSON representation of alarmChange Notification:

POST /client/listener

Accept: application/json

"eventType": "AlarmChangeNotification",

"eventTime": "2017-09-27T05:48:29.0Z",

"eventId": "1562233",

"event":

"alarm":

"id:": "ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"href": " http://api/alarm/ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--

Gi9/20@42",

"externalAlarmId": "cisco-7609-1937465789",

"alarmType": "QualityOfServiceAlarm",

"perceivedSeverity": "CRITICAL",

"probableCause": "Threshold crossed",

"specificProblem": "Inbound Traffic threshold crossed",

"alarmedObjectType": "ROUTER",

"alarmedObject": {

"id": "210875",

"href": " http://api/alarmedobject/210875"

"SourceSystemId": "OSS_1",

"alarmDetails": "Threshold on primary counter: Inbound Traffic (Mbits)

of

ROUTER_IF at resolution of 5 Minutes",

"alarmState": "UPDATED",

© TM Forum 2017. All Rights Reserved. Page 22

Alarm Management REST API Specification

"alarmRaisedTime": "2017-06-15T07:04:15.665Z",

"alarmChangedTime": "2017-06-15T07:04:15.666Z",

"alarmClearedTime": "",

"proposedRepairActions": "Switch in standby equipment",

"alarmReportingTime": "2017-06-15T07:04:15.666Z",

"ackState": "ACKNOWLEDGED",

"ackTime": "2017-06-15T07:04:19.666Z",

"ackUserId": "JOHN DOE",

"ackSystemId": "OSS",

"clearUserId": "",

"clearSystemId": "",

"plannedOutageIndication": "IN_SERVICE",

"alarmEscalation": 0,

"serviceAffecting": true,

"affectedService": [

"id": "Vlan_dot1_dot2",

"href": " http://api/service/Vlan_dot1_dot2"

],

"isRootCause": true,

"correlatedAlarm": [

"id": "Service_ Vlan_dot1_dot2_180880_54",

"href": "http://api/alarm/ Service_ Vlan_dot1_dot2_180880_54"

],

"parentAlarm": [

"id": "",

© TM Forum 2017. All Rights Reserved. Page 23

Alarm Management REST API Specification

"href": ""

],

"crossedThresholdInformation": {

"thresholdId": "Router IF_Inbount Traffic_001",

"thresholdRef": " http://api/threshold/Router IF_Inbount

Traffic_001",

"indicatorName": "IF_IN_MEGABITS ",

"observedValue": " 0.105",

"indicatorUnit": " MEGABITS",

"granularity": "5MINUTES",

"direction": "UP",

"thresholdCrossingDescription": "Threshold on primary counter:

Inbound

Traffic (Mbits) of ROUTER_IF"

},

"comments": [

"userId": "Jane Roe",

"time": "2017-06-15T07:04:20.666Z",

"systemId": "OSS_001",

"comment": "Problem reported to system engineering department"

}
}
}

© TM Forum 2017. All Rights Reserved. Page 24

Alarm Management REST API Specification

API OPERATION TEMPLATES

For every single of operation on the entities use the following templates.

The following Uniform Contract rules are used:

Operation on Entities Uniform API Operation Description

Query Entities GET Resource GET must be used to

retrieve a representation of
a resource.

Create Entity POST Resource POST must be used to

create a new resource

Partial Update of an Entity PATCH Resource PATCH must be used to

partially update a resource

Complete Update of an PUT Resource PUT must be used to

Entity completely update a
resource identified by its
resource URI

Remove an Entity DELETE Resource DELETE must be used to

remove a resource

Execute an Action on an POST on TASK Resource POST must be used to

Entity execute Task Resources

Other Request Methods POST on TASK Resource GET and POST must not
be used to tunnel other
request methods.

Filtering and attribute selection rules are described in the TMF REST Design Guidelines.

Notifications are also described in a subsequent section.

The following list of operation is [provided as part of the Alarm Management Interface:

© TM Forum 2017. All Rights Reserved. Page 25

Alarm Management REST API Specification

Single Alarm Operations

Uniform API Operation Mandatory/Optional Comments

POST /alarm O Create a new alarm

PATCH /alarm/{alarmId} O Modify an alarm

POST O DELETE an alarm, always

/alarm/{alarmId}/Clear by identifier

GET /alarm/{alarmId} O GET an alarm by identifier

Multiple Alarms Operations

Uniform API Operation Mandatory/Optional Comments

GET /alarms M GET a set of alarms by a

filter

POST /ackAlarms O Acknowledge a set of alarm

POST /unAckAlarms O Unacknowledge a set of

alarm

POST /clearAlarms O Clear a set of alarm

POST /commentAlarms O Comment a set of alarm

POST /groupAlarms O Group a set of alarm. This

is a result of Root Cause
Analysis

POST /ungroupAlarms O Ungroup a set of alarm.

This is a result of Root
Cause Analysis.

© TM Forum 2017. All Rights Reserved. Page 26

Alarm Management REST API Specification

POST /API/ALARM

The POST /api/alarm operation is used to create a new alarm at the target alarm management
system. The Mandatory and optional attributes are described in the table below.
The REQUEST message

Attribute Name Mandatory or Optional Comments

id O Accepted in entity-creation
requests if the server
supports the incoming
identifier as the reference to
create new resources

externalAlarmId M

alarmType M

perceivedSeverity M

probableCause M

specificProblem O

alarmedObjectType O

alarmedObject M A structure

id M

href O

sourceSystemId M

alarmDetails O

state O

alarmRaisedTime O

© TM Forum 2017. All Rights Reserved. Page 27

Alarm Management REST API Specification

proposedRepairActions O

alarmReportingTime O

plannedOutageIndication O

serviceAffecting O

affectedService O A structure

id M

href O

crossedThresholdInformation O A structure

thresholdId M

thresholdRef O

indicatorName O

observedValue O

indicatorUnit O

granularity O

direction O

thresholdCrossingDescription O

The REPONSE message will include all the alarm attributes

Behavior:

• Return status codes

© TM Forum 2017. All Rights Reserved. Page 28

Alarm Management REST API Specification

o 200 OK - the request was successful

o 400 Bad Request - error

REQUEST

POST /api/alarm/
Content-type: application/json
{

"id:": "ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"href": "",

"externalAlarmId": "cisco-7609-1937465789",

"alarmType": "QualityOfServiceAlarm",

"perceivedSeverity": "CRITICAL",

"probableCause": "Threshold crossed",

"specificProblem": "Inbound Traffic threshold crossed",

"alarmedObjectType": "ROUTER",

"alarmedObject": {

"id": "210875",

"href": ""

"SourceSystemId": "OSS_1",

"alarmDetails": "Threshold on primary counter: Inbound Traffic (Mbits) of

ROUTER_IF at resolution of 5 Minutes",

"alarmState": "RAISED",

"alarmRaisedTime": "2017-06-15T07:04:15.665Z",

"proposedRepairActions": "Switch in standby equipment",

"alarmReportingTime": "2017-06-15T07:04:15.666Z",

"plannedOutageIndication": "IN_SERVICE",

"serviceAffecting": true,

"affectedService": [

© TM Forum 2017. All Rights Reserved. Page 29

Alarm Management REST API Specification

"id": "Vlan_dot1_dot2",

"href": ""

],

"crossedThresholdInformation": {

"thresholdId": "Router IF_Inbount Traffic_001",

"thresholdRef": "string",

"indicatorName": " IF_IN_MEGABITS ",

"observedValue": " 0.105",

"indicatorUnit": " MEGABITS",

"granularity": "5MINUTES",

"direction": "UP",

"thresholdCrossingDescription": "Threshold on primary counter: Inbound

Traffic (Mbits) of ROUTER_IF"

RESPONSE

201

Content-Type: application/json
{

"id:": "ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"href": "http://api/alarm/ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"externalAlarmId": "cisco-7609-1937465789",

"alarmType": "QualityOfServiceAlarm",

"perceivedSeverity": "CRITICAL",

"probableCause": "Threshold crossed",

"specificProblem": "Inbound Traffic threshold crossed",

"alarmedObjectType": "ROUTER",

"alarmedObject": {

© TM Forum 2017. All Rights Reserved. Page 30

Alarm Management REST API Specification

"id": "210875",

"href": "http://api/alarmedobject/210875"

"SourceSystemId": "TG",

"alarmDetails": "Threshold on primary counter: Inbound Traffic (Mbits) of

ROUTER_IF at resolution of 5 Minutes",

"alarmState": "RAISED",

"alarmRaisedTime": "2017-06-15T07:04:15.665Z",

"proposedRepairActions": "Switch in standby equipment",

"alarmReportingTime": "2017-06-15T07:04:15.666Z",

"plannedOutageIndication": "IN_SERVICE",

"serviceAffecting": true,

"affectedService": [

"id": "Vlan_dot1_dot2",

"href": ""

],

"crossedThresholdInformation": {

"thresholdId": "Router IF_Inbount Traffic_001",

"thresholdRef": ""http://api/threshold/Router IF_Inbount Traffic_001",

"indicatorName": " IF_IN_MEGABITS ",

"observedValue": " 0.105",

"indicatorUnit": " MEGABITS",

"granularity": "5MINUTES",

"direction": "UP",

"thresholdCrossingDescription": "Threshold on primary counter: Inbound

Traffic (Mbits) of ROUTER_IF"

© TM Forum 2017. All Rights Reserved. Page 31

Alarm Management REST API Specification

PATCH /API/ALARM/{ALARMID}

The PATCH /api/alarm/{alarmid} operation is used to modify an existing alarm at the target alarm
management system. The Mandatory and optional attributes are described in the table below.

Attribute Name Mandatory or Optional Comments

href O

perceivedSeverity O

probableCause O

specificProblem O

alarmDetails O

alarmChangedTime O

proposedRepairActions O

plannedOutageIndication O

alarmEscalation O

serviceAffecting O

affectedService O A structure

id M

href O

crossedThresholdInformation O A structure

thresholdId M

© TM Forum 2017. All Rights Reserved. Page 32

Alarm Management REST API Specification

thresholdRef O

indicatorName O

observedValue O

indicatorUnit O

granularity O

direction O

thresholdCrossingDescription O

The REPONSE message

Attribute Name Mandatory or Optional Comments

id M

href M

alarmChangedTime M

Note: It is assumed that the system/user that is modifying an alarm is the same system/user that created it.

Behavior:

• Return status codes

o 201 Created - the request was successful
o 400 Bad Request - error

REQUEST

PATCH /api/alarm/ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42
Content-type: application/merge-patch+json
{

© TM Forum 2017. All Rights Reserved. Page 33

Alarm Management REST API Specification

"id:": "ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"href": "http://api/alarm/ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"perceivedSeverity": "CRITICAL",

"probableCause": "Threshold crossed",

"specificProblem": "Inbound Traffic threshold crossed",

"alarmDetails": "Threshold on primary counter: Inbound Traffic (Mbits) of

ROUTER_IF at resolution of 5 Minutes",

"alarmChangedTime": "2017-06-15T07:04:15.666Z",

"proposedRepairActions": "Switch in standby equipment",

"plannedOutageIndication": "IN_SERVICE",

"alarmEscalation": 0,

"serviceAffecting": true,

"affectedService": [

"id": "Vlan_dot1_dot2",

"href": ""

],

"crossedThresholdInformation": {

"thresholdId": "Router IF_Inbount Traffic_001",

"thresholdRef": "",

"indicatorName": " IF_IN_MEGABITS ",

"observedValue": " 0.105",

"indicatorUnit": " MEGABITS",

"granularity": "5MINUTES",

"direction": "UP",

"thresholdCrossingDescription": "Threshold on primary counter: Inbound

Traffic (Mbits) of ROUTER_IF"

© TM Forum 2017. All Rights Reserved. Page 34

Alarm Management REST API Specification

RESPONSE

201
Content-Type: application/json
{

"id:": "ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"href": "http://api/alarm/ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"alarmChangedTime": "2017-06-15T07:04:15.666Z",

© TM Forum 2017. All Rights Reserved. Page 35

Alarm Management REST API Specification

POST /API/ALARM/{ALARMID}/CLEAR

The POST /api/alarm/{ALARMID}/Clear operation is used to clear an alarm at the target alarm
management system. The Mandatory and optional attributes are described in the table below.
The REQUEST message

Attribute Name Mandatory or Optional Comments

alarmClearedTime O

clearUserId M Either clearUserId or

clearSystemId should be
populated

clearSystemId M Either clearUserId or

clearSystemId should be
populated

The REPONSE message

Attribute Name Mandatory or Optional Comments

id M

href O

alarmClearedTime M

clearUserId M Either clearUserId or

clearSystemId should be
populated

clearSystemId M Either clearUserId or

clearSystemId should be
populated

Behavior:

© TM Forum 2017. All Rights Reserved. Page 36

Alarm Management REST API Specification

• Returns HTTP/1.1 status code 201 if the request was successful.

• Returns HTTP/1.1 status code 400 (Bad request) if content is invalid (missing required
attributes).

REQUEST

POST /api/alarm/ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42/clear
Content-Type: application/json

"alarmClearedTime": "2017-06-15T07:04:19.666Z",

"clearUserId": "JOHN DOE",

"clearSystemId": "OSS_01"

RESPONSE

201
Content-Type: application/json

"id:": "ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"href": "http://api/alarm/ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"alarmClearedTime": "2017-06-15T07:04:19.666Z",

"clearUserId": "JOHN DOE",

"clearSystemId": "OSS_01"

GET /API/ALARM/{ALARMID}

The GET /api/alarm/{ALARMID} operation is used get the details of a specific alarm at the target
alarm management system based on its identifier.

The REQUEST message does not include any attributes as this GET operation is providing the
identifier of the alarm in its header.

© TM Forum 2017. All Rights Reserved. Page 37

Alarm Management REST API Specification

The REPONSE message may have different attributes based on the attribute selection. These
attributes are a subset of the alarm object attributes.

Behavior:

• Return status codes

o Returns HTTP/1.1 status code 201 if the request was successful.
o Returns HTTP/1.1 status code 400 (Bad request) if content is invalid (missing
required attributes).

REQUEST

Get /api/alarm/ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42
Content-Type: application/json

RESPONSE

200
Content-Type: application/json
{
"id:": "ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"href": "http://api/alarm/ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"externalAlarmId": "cisco-7609-1937465789",

"alarmType": "QualityOfServiceAlarm",

"perceivedSeverity": "CRITICAL",

"probableCause": "Threshold crossed",

"specificProblem": "Inbound Traffic threshold crossed",

"alarmedObjectType": "ROUTER",

"alarmedObject": {

"id": "210875",

"href": ""

"SourceSystemId": "TG",

"alarmDetails": "Threshold on primary counter: Inbound Traffic (Mbits) of

ROUTER_IF at resolution of 5 Minutes",

"alarmState": "RAISED",

"alarmRaisedTime": "2017-06-15T07:04:15.665Z",

© TM Forum 2017. All Rights Reserved. Page 38

Alarm Management REST API Specification

"alarmChangedTime": "2017-06-15T07:04:15.666Z",

"alarmClearedTime": "",

"proposedRepairActions": "Switch in standby equipment",

"alarmReportingTime": "2017-06-15T07:04:15.666Z",

"ackState": "ACKNOWLEDGED",

"ackTime": "2017-06-15T07:04:19.666Z",

"ackUserId": "JOHN DOE",

"ackSystemId": "OSS",

"clearUserId": "",

"clearSystemId": "",

"plannedOutageIndication": "IN_SERVICE",

"alarmEscalation": 0,

"serviceAffecting": true,

"affectedService": [

"id": "Vlan_dot1_dot2",

"href": ""

],

"isRootCause": true,

"correlatedAlarm": [

"id": "Service_ Vlan_dot1_dot2_180880_54",

"href": " http://api/alarm/ Service_ Vlan_dot1_dot2_180880_54"

],

"parentAlarm": [

"id": "",

"href": ""

© TM Forum 2017. All Rights Reserved. Page 39

Alarm Management REST API Specification

],

"crossedThresholdInformation": {

"thresholdId": "Router IF_Inbount Traffic_001",

"thresholdRef": "",

"indicatorName": " IF_IN_MEGABITS ",

"observedValue": " 0.105",

"indicatorUnit": " MEGABITS",

"granularity": "5MINUTES",

"direction": "UP",

"thresholdCrossingDescription": "Threshold on primary counter: Inbound

Traffic (Mbits) of ROUTER_IF"

},

"comments": [

"userId": "Jane Doe",

"time": "2017-06-15T07:04:20.666Z",

"systemId": "OSS_001",

"comment": "Problem reported to system engineering department"

© TM Forum 2017. All Rights Reserved. Page 40

Alarm Management REST API Specification

GET /API/ALARMS

The GET /api/alarm/ operation is used get details of a specific alarm at the target alarm
management system based on a filter.

Behavior:

• What status and exception codes are returned.

• Returns HTTP/1.1 status code 200 if the request was successful.
• Any other special return and/or exception codes.

In the example below, it is requested to get the id, href and perceivedSeverity and
alarmRaisedTime attributes of all active alarms that were raised after a certain date & time.

REQUEST

GET /api/alarm/fields=id,href,perceivedSeverity& alarmRaisedTime.gt="2017-06-31T00:00:00.000Z"

Accept: application/json

RESPONSE

200
Content-Type: application/json
[
{
"id:": "ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"href": "http://api/alarm/ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"perceivedSeverity": "CRITICAL",

"alarmRaisedTime": "2017-06-15T07:04:15.665Z"

},
{
"id:": "ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@49",

"href": "http://api/alarm/ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@49",

"perceivedSeverity": "MAJOR",

"alarmRaisedTime": "2017-06-15T07:04:15.665Z"

}
]

© TM Forum 2017. All Rights Reserved. Page 41

Alarm Management REST API Specification

POST /API/ACKALARMS

The POST /api/ackalarms operation is used to acknowledge a set of alarms at the target alarm
management system. The Mandatory and optional attributes are described in the table below.
The REQUEST message (used as a template for acknowledging alarms)

Attribute Name Mandatory or Optional Comments

id O An array. Part of a filter

alarmedObjectType O Part of a filter

alarmedObject O An array. Part of a filter

id M Part of a filter

alarmRaisedTime O Part of a filter

ackUserId M Part of a filter/Input. Either

ackUserId or ackSystemId
has to be populated

ackSystemId M Part of a filter/Input. Either

ackUserId or ackSystemId
has to be populated

ackTime O An input attribute

Notes;

• The ackState will be modified on the target system as a result of this operation.
• If no filtering attribute is populated, all the alarms of the source User/System will be acknowledged

The REPONSE message

Attribute Name Mandatory or Optional Comments

AckedAlarms M A list (the structure)

© TM Forum 2017. All Rights Reserved. Page 42

Alarm Management REST API Specification

id M

href O

ackUserId M Either ackUserId or

ackSystemId has to be
populated

ackSystemId M Either ackUserId or

ackSystemId has to be
populated

ackTime O

Behavior:

• Return status codes

o 200 OK - the request was successful
o 400 Bad Request - error

In the example below it is required to acknowledge all the alarms coming from OSS_1

REQUEST

POST /api/ackalarms
Content-Type: application/json

"id:": "",

"href":,""

"alarmedObjectType": ""

"alarmedObject": {

"id": ""

"href": ""

"alarmRaisedTime": ""

"ackUserId": ""

© TM Forum 2017. All Rights Reserved. Page 43

Alarm Management REST API Specification

"ackSystemId": "OSS_1",

"ackTime": "2017-06-15T07:04:19.666Z",

RESPONSE

200
[

"id:": "ROUTER@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"href": " http://api/alarm/ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"ackUserId": "JOHN DOE",

"ackSystemId": "OSS_1",

"ackTime": "2017-06-15T07:04:19.666Z",

},
{

"id:": " ROUTER@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@43",

"href": "http://api/alarm/ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@43",

"ackUserId": "JANE DOE",

"ackSystemId": "OSS_1",

"ackTime": "2017-06-15T07:04:19.666Z",

}
]

© TM Forum 2017. All Rights Reserved. Page 44

Alarm Management REST API Specification

POST /API/UNACKALARMS

The POST /api/unackalarms operation is used to un-acknowledge a set of alarms at the target
alarm management system. The Mandatory and optional attributes are described in the table
below.

The REQUEST message (used as a template for unacknowledging alarms)

Attribute Name Mandatory or Optional Comments

id O An array. Part of a filter

alarmedObjectType O Part of a filter

alarmedObject O An array. Part of a filter

id M Part of a filter

alarmRaisedTime O Part of a filter

ackUserId M Part of a filter/Input. Either

ackUserId or ackSystemId
has to be populated

ackSystemId M Part of a filter/Input. Either

ackUserId or ackSystemId
has to be populated

ackTime O An input attribute

Notes;

• The ackState will be modified on the target system as a result of this operation.
• If no filtering attribute is populated, all the alarms of the source User/System will be acknowledged

The REPONSE message

Attribute Name Mandatory or Optional Comments

© TM Forum 2017. All Rights Reserved. Page 45

Alarm Management REST API Specification

AckedAlarms M A list (the structure)

id M

href O

ackUserId M Either ackUserId or

ackSystemId has to be
populated

ackSystemId M Either ackUserId or

ackSystemId has to be
populated

ackTime O An input attribute

Behavior:

• Return status codes

o Returns HTTP/1.1 status code 201 if the request was successful.
o Returns HTTP/1.1 status code 400 (Bad request) if content is invalid (missing
required attributes).

In the example below it is required to acknowledge all the alarms coming from routers.

REQUEST

POST /api/unackalarms
Content-Type: application/json

"id:": "",

"href": "",

"alarmedObjectType": "ROUTER",

"alarmedObject": {

"id": "",

"href": ""

© TM Forum 2017. All Rights Reserved. Page 46

Alarm Management REST API Specification

"alarmRaisedTime": "",

"ackUserId": "",

"ackSystemId": "OSS",

"ackTime": "2017-06-15T07:04:19.666Z",

},
{

RESPONSE

201
[

"id:": "ROUTER@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"href": " http://api/alarm/ROUTER@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"ackUserId": "",

"ackSystemId": "OSS",

"ackTime": "2017-06-15T07:04:19.666Z",

},
{

"id:": " ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@43",

"href": "http://api/alarm/ROUTER@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"ackUserId": "",

"ackSystemId": "OSS",

"ackTime": "2017-06-15T07:04:19.666Z",

}
]

© TM Forum 2017. All Rights Reserved. Page 47

Alarm Management REST API Specification

POST /API/CLEARALARMS

The POST /api/clearalarms operation is used to clear alarm at the target alarm management
system by a filter. The Mandatory and optional attributes are described in the table below.
The REQUEST message (used as a template for clearing alarms)

Attribute Name Mandatory or Optional Comments

id O An array. Part of a filter

alarmType O Part of a filter

probableCause O Part of a filter

alarmedObjectType O Part of a filter

alarmedObject O A list. Part of a filter

id M Part of a filter

clearUserId M Part of a filter/Input. Either

clearUserId or
clearSystemId has to be
populated

clearSystemId M Part of a filter/Input. Either

clearUserId or
clearSystemId has to be
populated

alarmClearedTime O To be used by the Alarm

system

Notes;

• If no filtering attribute is populated, all the alarms of the source User/System will be cleared

© TM Forum 2017. All Rights Reserved. Page 48

Alarm Management REST API Specification

The REPONSE message

Attribute Name Mandatory or Optional Comments

clearedAlarms A list

id M

href O

Behavior:

• Return status codes

o Returns HTTP/1.1 status code 201 if the request was successful.
o Returns HTTP/1.1 status code 400 (Bad request) if content is invalid (missing
required attributes).

In the example below it is required to acknowledge all the alarms from alarmed objects with id =
210875 coming from OSS_01

REQUEST

POST /api/unackalarms
Content-Type: application/json

"id:": "",

"href": "",

"alarmType": "",

"probableCause":,"",

"alarmedObjectType": "",

"alarmedObject": {

"id": "210875",

"href": ""

},

© TM Forum 2017. All Rights Reserved. Page 49

Alarm Management REST API Specification

"clearUserId": "",

"clearSystemId": "OSS_01",

"alarmClearedTime": "2017-06-15T07:04:19.666Z "

RESPONSE

201
{

"id:": "ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"href": "http://api/alarm/ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42"

© TM Forum 2017. All Rights Reserved. Page 50

Alarm Management REST API Specification

POST /API/COMMENTALARMS

The POST /api/commentalarms operation is used to add comments on a set of alarms (a

comment per alarm) at the target alarm management system. The Mandatory and optional
attributes are described in the table below.

The REQUEST message, an array of the following (for each comment)

Attribute Name Mandatory or Optional Comments

alarmId M A list

Comment M

userId M Either usreId or systemId

should be deployed

systemId M Either usreId or systemId

should be deployed

time O

Comment M

The REPONSE message

Attribute Name Mandatory or Optional Comments

commentedAlarms A list

id M

href O

Behavior:

• Return status codes

o Returns HTTP/1.1 status code 201 if the request was successful.

© TM Forum 2017. All Rights Reserved. Page 51

Alarm Management REST API Specification

o Returns HTTP/1.1 status code 400 (Bad request) if content is invalid (missing
required attributes).

REQUEST

POST /api/commentalarm
Content-Type: application/json

"id:": "ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"href": "http://api/alarm/ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"comments": [

"userId": "Jane Doe",

"time": "2017-06-15T07:04:20.666Z",

"systemId": "OSS_001",

"comment": "Problem reported to system engineering department"

RESPONSE

201
{

"id:": "ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

"href": "http://api/alarm/ROUTER_IF@Cisco-7609-6-4-4-4-14-14-4--Gi9/20@42",

© TM Forum 2017. All Rights Reserved. Page 52

Alarm Management REST API Specification

POST /API/GROUPALARMS

The POST /api/groupAlarms is used to group alarm, applying the result of Root Cause Analysis
reasoning at the target alarm management system. The Mandatory and optional attributes are
described in the table below.

The REQUEST message

Attribute Name Mandatory or Optional Comments

parentAlarm M

id M

href O

correlatedAlarms M A list

id M

href O

changeTime O

sourceSystemId M

The REPONSE message

Attribute Name Mandatory or Optional Comments

parentAlarm M

id M

href O

correlatedAlarms M A list

id M

© TM Forum 2017. All Rights Reserved. Page 53

Alarm Management REST API Specification

href O

changeTime O

sourceSystemId M

Note: The isRootCause attribute on the target Alarm Management system will be modified as a result of this
operation

Behavior:

• Return status codes

o Returns HTTP/1.1 status code 201 if the request was successful.
o Returns HTTP/1.1 status code 400 (Bad request) if content is invalid (missing
required attributes).

REQUEST

POST /api/groupalarms
Content-Type: application/json

"parentAlarm": [

"id": "ALR_PARENT_1",

"href": "http://api/alarm/ ALR_PARENT_1"

],

"correlatedAlarm": [

"id": "ALR_CHILD_1",

"href": "http://api/alarm/ ALR_CHILD_1"

},

© TM Forum 2017. All Rights Reserved. Page 54

Alarm Management REST API Specification

"id": "ALR_CHILD_2",

"href": "http://api/alarm/ ALR_CHILD_1""

],

"alarmChangedTime": "2017-06-15T07:04:15.666Z",

"SourceSystemId": "OSS_1"

RESPONSE

201
[

"parentAlarm":

"id": "ALR_PARENT_1",

"href": "http://api/alarm/ ALR_PARENT_1"

"correlatedAlarm": [

"id": "ALR_CHILD_1",

"href": "http://api/alarm/ ALR_CHILD_1"

},

"id": "ALR_CHILD_2",

"href": " http://api/alarm/ALR_CHILD_12"

],

"alarmChangedTime": "2017-06-15T07:04:15.666Z",

"SourceSystemId": "OSS_1"

© TM Forum 2017. All Rights Reserved. Page 55

Alarm Management REST API Specification

POST /API/UNGROUPALARMS

The POST /api/ungroupAlarms is used to un-group alarms, as a result of Root Cause Analysis
reasoning at the target alarm management system. The Mandatory and optional attributes are
described in the table below.

The REQUEST message

Attribute Name Mandatory or Optional Comments

parentAlarm M

id M

href O

correlatedAlarms M A list

id M

href O

changeTime O

sourceSystemId M

The REPONSE message

Attribute Name Mandatory or Optional Comments

parentAlarm M

id M

href O

unCorrelatedAlarms M A list

© TM Forum 2017. All Rights Reserved. Page 56

Alarm Management REST API Specification

id M

href O

changeTime O

sourceSystemId M

Note: The isRootCause attribute on the target Alarm Management system will be modified as a result of this
operation

Behavior:

• Return status codes

o Returns HTTP/1.1 status code 201 if the request was successful.
o Returns HTTP/1.1 status code 400 (Bad request) if content is invalid (missing
required attributes).

REQUEST

"parentAlarm":

"id": "ALR_PARENT_1",

"href": "http://api/alarm/ ALR_PARENT_1"

"correlatedAlarm": [

"id": "ALR_CHILD_1",

"href": "http://api/alarm/ ALR_CHILD_1"

},

© TM Forum 2017. All Rights Reserved. Page 57

Alarm Management REST API Specification

"id": "ALR_CHILD_2",

"href": "http://api/alarm/ ALR_CHILD_1""

],

"alarmChangedTime": "2017-06-15T07:04:15.666Z",

"SourceSystemId": "OSS_1"

RESPONSE

201
[

"parentAlarm":

"id": "ALR_PARENT_1",

"href": "http://api/alarm/ ALR_PARENT_1"

},

"correlatedAlarm": [

"id": "ALR_CHILD_1",

"href": "http://api/alarm/ ALR_CHILD_1"

},

"id": "ALR_CHILD_2",

"href": " http://api/alarm/ALR_CHILD_12"

],

"alarmChangedTime": "2017-06-15T07:04:15.666Z",

"SourceSystemId": "OSS_1"

© TM Forum 2017. All Rights Reserved. Page 58

Alarm Management REST API Specification

"alarmChangedTime": "2017-06-15T07:04:15.666Z",

"SourceSystemId": "TG"

© TM Forum 2017. All Rights Reserved. Page 59

Alarm Management REST API Specification

API NOTIFICATION TEMPLATES

It is assumed that the Pub/Sub uses the Register and UnRegister mechanisms described in the
REST Guidelines reproduced below.

REGISTER LISTENER POST /HUB

Description:

Sets the communication endpoint address the service instance must use to deliver
information about its health state, execution state, failures and metrics. Subsequent
POST calls will be rejected by the service if it does not support multiple listeners. In
this case DELETE /api/hub/{id} must be called before an endpoint can be created
again.
Behavior:

Returns HTTP/1.1 status code 204 if the request was successful.

Returns HTTP/1.1 status code 409 if request is not successful.

REQUEST

POST /api/hub
Accept: application/json

{"callback": "http://in.listener.com"}

RESPONSE

201
Content-Type: application/json
Location: /api/hub/42

{"id":"42","callback":"http://in.listener.com","query":null}

UNREGISTER LISTENER DELETE HUB/{ID}

© TM Forum 2017. All Rights Reserved. Page 60

Alarm Management REST API Specification

Description:

Clears the communication endpoint address that was set by creating the Hub.

Behavior:

Returns HTTP/1.1 status code 204 if the request was successful.

Returns HTTP/1.1 status code 404 if the resource is not found.

REQUEST

DELETE /api/hub/{id}
Accept: application/json

RESPONSE

204

PUBLISH {EVENTTYPE} POST /LISTENER

Description:

Provide the Event description

Behavior:

Returns HTTP/1.1 status code 201 if the service is able to set the configuration.

REQUEST

POST /client/listener
Accept: application/json

"event": {

EVENT BODY
},
"eventType": "eventType"
}

© TM Forum 2017. All Rights Reserved. Page 61

Alarm Management REST API Specification

RESPONSE

201
Content-Type: application/json

© TM Forum 2017. All Rights Reserved. Page 62

Alarm Management REST API Specification

RELEASE HISTORY

Release Date Release led by: Description

Number

Release 17.0.0 20-Sep-2017 Yuval Stein, TEOCO First Release of the Document.

Pierre Gauthier,

TM Forum

Release 17.0.1 04-Dec-2017 Adrienne Walcott Updated to reflect TM Forum

TM Forum Approved Status
Version 1.0.1

© TM Forum 2017. All Rights Reserved. Page 63