openapi: 3.0.1 info: title: Alarm Management description: > **This file forms part of Mplify 146** **This API implements part of Business Requirements & Use Cases described in Mplify 133.1** Mplify Alarm Management is used to notify listening client about a specific event that has occurred. An alarm may or may not represent an error. The Alarm can indicate that a TCA has been crossed. Not all alarms are an indication of a failure. List of use cases by supported the API: - Retrieve Alarm List - Retrieve Alarm by ID - Subscribe for Alarms - Unsubscribe to Alarms Copyright 2025 Mplify Alliance and its contributors This file includes content based on the TM Forum Alarm Management API (TMF642 v5.0.0) available at https://www.tmforum.org/oda/open-apis/directory/alarm-management-api-TMF642/v5.0, which is licensed by the TM Forum under the Apache License version 2.0. Such content has been modified by the Mplify Alliance and its contributors. version: 3.0.0 servers: - url: 'https://{serverBase}/mefApi/legato/alarmManagement/v3/' variables: serverBase: description: The base of SOF's URL. default: mplify.net tags: - name: alarm paths: /alarm: get: tags: - alarm summary: List or find Alarm objects. description: >- The Buyer/Client requests a list of Alarms using none or more of the filter criteria. The Seller/Server returns a summarized list of Alarms. For each Alarm returned, the Seller/Server also provides a Alarm Identifier that uniquely identifiers this Alarm within the Seller/Server. The order of the elements returned to the Buyer/Client is defined by the Seller/Server (e.g. natural order) and does not change between the pages. operationId: listAlarms parameters: - name: id in: query description: The identifier of the Alarm. required: false schema: type: string - name: alarmChangedTime.gt in: query description: Date when the alarm was changed - greater than. required: false schema: type: string format: date-time - name: alarmChangedTime.lt in: query description: Date when the alarm was changed - lower than. required: false schema: type: string format: date-time - name: alarmClearedTime.gt in: query description: Date when the alarm was cleared - greater than. required: false schema: type: string format: date-time - name: alarmClearedTime.lt in: query description: Date when the alarm was cleared - lower than. required: false schema: type: string format: date-time - name: alarmReportingTime.gt in: query description: Date when the alarm was reported - greater than. required: false schema: type: string format: date-time - name: alarmReportingTime.lt in: query description: Date when the alarm was reported - lower than. required: false schema: type: string format: date-time - name: alarmType in: query description: Type of the Alarm. required: false schema: $ref: '#/components/schemas/AlarmType' - name: alarmedObjectType in: query description: Type of the Alarm Object. required: false schema: type: string - name: perceivedSeverity in: query description: Perceived Severity of the Alarm. required: false schema: $ref: '#/components/schemas/PerceivedSeverity' - name: plannedOutageIndicator in: query description: Planned Outage Indicator of the Alarm. required: false schema: $ref: '#/components/schemas/PlannedOutageIndicator' - name: reportingSystemId in: query description: Alarm Reporting system identity. required: false schema: type: string - name: serviceAffecting in: query description: Service Affecting Alarms. required: false schema: type: boolean - name: state in: query description: Alarm state. required: false schema: $ref: '#/components/schemas/AlarmState' - name: affectedServiceId in: query description: Affected Service Id. required: false schema: type: string - name: correlatedAlarmId in: query description: Correlated Alarm Id. required: false schema: type: string - name: offset in: query description: >- Requested index for start of item to be provided in response requested by the client. Note that the index starts with "0". required: false schema: type: integer - name: limit in: query description: Requested number of resources to be provided in response. required: false schema: type: integer format: int32 responses: '200': description: "'OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)'" headers: X-Pagination-Throttled: description: >- Used to indicate that result page was throttled to maximum possible size and there are additional results that can be fetched. schema: type: boolean X-Total-Count: description: >- The total number of matching items. E.g. if there are 50 matching items in total, but the request has offset=10 and limit=10, then the X-Total-Count is 50. schema: type: integer X-Result-Count: description: The number of items included in the response. schema: type: integer content: application/json;charset=utf-8: schema: type: array items: $ref: '#/components/schemas/Alarm_Common' '400': description: Bad Request content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' '422': description: Unprocessable entity due to the business validation problems content: application/json;charset=utf-8: schema: type: array items: $ref: '#/components/schemas/Error422' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' '/alarm/{id}': get: tags: - alarm summary: Retrieves an Alarm by ID. description: >- The Buyer/Client requests detailed information about a single Alarm based on the Alarm Identifier. operationId: retrieveAlarm parameters: - name: id in: path description: Identifier of the Alarm required: true schema: type: string responses: '200': description: "'OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)'" content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Alarm' '400': description: Bad Request content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' '404': description: Not Found content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error404' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' /hub: post: tags: - events subscription summary: Register a listener description: >- The Buyer/Client or Administrator requests to subscribe to Alarm Notifications. operationId: registerListener requestBody: description: Data containing the callback endpoint to deliver the information. content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/EventSubscriptionInput' required: true responses: '201': description: Subscribed content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/EventSubscription' '400': description: Bad Request content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' '501': description: Method not implemented. content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error501' '/hub/{id}': get: tags: - events subscription summary: Retrieves a Hub by ID. description: >- The Buyer/Client requests detailed information about a single Notification Hub based on the Hub Identifier. operationId: retrieveHub parameters: - name: id in: path description: Identifier of the Hub required: true schema: type: string responses: '200': description: Success content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/EventSubscription' '400': description: Bad Request content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' '404': description: Not Found content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error404' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' '501': description: Method not implemented. content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error501' delete: tags: - events subscription summary: Unregister a listener description: >- The Buyer/Client or Administrator requests to unsubscribe from Alarm Notifications. operationId: unregisterListener parameters: - name: id in: path description: The id of the registered listener required: true schema: type: string responses: '204': description: Deleted '400': description: Bad request content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' '404': description: Not Found content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error404' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' '501': description: Method not implemented. content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error501' components: schemas: Alarm: allOf: - $ref: '#/components/schemas/Alarm_Common' - description: A definition of an Alarm. type: object properties: alarmedObject: description: >- Identifies the Managed Object instance associated with the alarm. type: array items: $ref: '#/components/schemas/AlarmedObjectRef' comment: type: array items: $ref: '#/components/schemas/Comment' externalAlarmId: description: An identifier of the alarm in the source system. type: string isRootCause: description: Indicates whether the alarm is a root cause alarm. type: boolean parentAlarm: $ref: '#/components/schemas/AlarmRef' probableCause: $ref: '#/components/schemas/ProbableCause' alarmSpecificAttributes: $ref: '#/components/schemas/AlarmSpecificAttributes' sourceSystemId: description: Source system identity. type: string specificProblem: description: Provides more specific information about the alarm. type: string required: - alarmedObject - isRootCause AlarmedObjectRef: type: object properties: id: description: unique identifier of the Alarm type: string href: description: hyperlink to the referenced Alarm type: string '@referredType': description: >- The actual type of the target instance when needed for disambiguation. type: string required: - id - '@referredType' AlarmRef: type: object properties: id: description: unique identifier of the Alarm type: string href: description: hyperlink to the referenced Alarm type: string required: - id AlarmSpecificAttributes: description: >- AlarmSpecificAttributes is used as an extension for Alarm specific payload. The @type attribute is used as a discriminator. type: object properties: '@type': description: The named type must be a subclass of AlarmSpecificAttributes. type: string required: - '@type' discriminator: propertyName: '@type' AlarmState: description: |- Defines the alarm state during its life cycle. | state | Mplify 133.1 name | Description | | ---------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `acknowledged` | Acknowledged | An alarm that is still active but has been acknowledged by an operator, meaning the operator is aware of the issue and has taken note for action.| | `cleared` | Cleared | Indicates that the underlying fault or abnormal condition that triggered the alarm has been resolved, and the alarm is no longer active. | | `unAcknowledged` | Unacknowledged | An alarm that has been raised and is still visible to the operator, but has not yet been acknowledged. | type: string enum: - acknowledged - cleared - unAcknowledged AlarmType: description: |- Categorize the alarm. Values as defined in X.733 8.1.1 or 3GPP TS32.111. | state | Mplify 133.1 name | Description | | -------------------------------- | -------------------------|------------------------------------------------------------------------------------------------------------------------------------------------| | `communicationsAlarm` | Communications Alarm | An alarm of this type is principally associated with the procedures and/or processes required to convey information from one point to another. | | `processingErrorAlarm` | Processing Error Alarm | An alarm of this type is principally associated with a software or processing fault. | | `environmentalAlarm` | Environmental Alarm | An alarm of this type is principally associated with a condition relating to an enclosure in which the equipment resides. | | `qualityOfServiceAlarm` | Quality of Service Alarm | An alarm of this type is principally associated with a degradation in the quality of a service. | | `equipmentAlarm` | Equipment Alarm | An alarm of this type is principally associated with an equipment fault. | | `communicationsAlarm` | Communications Alarm | An alarm of this type is principally associated with the procedures and/or processes required to convey information from one point to another. | | `processingErrorAlarm` | Processing Error Alarm | An alarm of this type is principally associated with a software or processing fault. | | `environmentalAlarm` | Environmental Alarm | An alarm of this type is principally associated with a condition relating to an enclosure in which the equipment resides. | | `qualityOfServiceAlarm` | Quality of Service Alarm | An alarm of this type is principally associated with a degradation in the quality of a service. | | `equipmentAlarm` | Equipment Alarm | An alarm of this type is principally associated with an equipment fault. | | `integrityViolation` | Integrity Violation | Information may have been illegally modified, inserted or deleted. | | `operationalViolation` | Operational Violation | The unavailability, malfunction or incorrect invocation of a service. | | `physicalViolation` | Physical Violation | A physical resource has been violated in a way that suggests a security attack. | | `securityService` | Security Service | A security attack has been detected by a security service. | | `mechanismViolation` | Mechanism Violation | A security attack has been detected by a security mechanism. | | `timeDomainViolation` | Time Domain Violation | An event has occurred at an unexpected or prohibited time. | type: string enum: - communicationsAlarm - processingErrorAlarm - environmentalAlarm - qualityOfServiceAlarm - equipmentAlarm - integrityViolation - operationalViolation - physicalViolation - securityService - mechanismViolation - timeDomainViolation Alarm_Common: description: A definition of an Alarm. type: object properties: id: description: The identifier of the Alarm. type: string href: description: Hyperlink reference type: string format: uri affectedService: description: Affected services type: array items: $ref: '#/components/schemas/ServiceRef' alarmChangedTime: description: >- Indicates the last date and time when the alarm is changed on the alarm owning system. Any change to the alarm whether coming from the alarmed resource is changing this time. type: string format: date-time alarmClearedTime: description: >- Indicates the time (as a date + time) at which the alarm is cleared at the source. type: string format: date-time alarmDetails: description: Contains further information on the Alarm. type: string alarmedObjectType: description: >- The type (class) of the Managed Object associated with the event e.g. port. type: string alarmRaisedTime: description: >- The time that an alarm was raised. This time may differ from the Alarm Reported Time type: string format: date-time alarmReportingTime: description: >- Indicates the time (as a date + time) at which the alarm was reported by the owning OSS. It might be different from the alarm-RaisedTime. 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. type: string format: date-time correlatedAlarm: description: Correlated Alarms type: array items: $ref: '#/components/schemas/AlarmRef' alarmType: $ref: '#/components/schemas/AlarmType' perceivedSeverity: $ref: '#/components/schemas/PerceivedSeverity' plannedOutageIndicator: $ref: '#/components/schemas/PlannedOutageIndicator' reportingSystemId: description: Reporting system identity. type: string serviceAffecting: description: Indicates whether the alarm affects service or not. type: boolean state: $ref: '#/components/schemas/AlarmState' required: - alarmDetails - alarmRaisedTime - alarmReportingTime - alarmType - id - perceivedSeverity - state - serviceAffecting Comment: description: A comment entered on the alarm type: object properties: description: description: The text of the comment. type: string systemIdentifier: description: The system identifier of the system that set the comment. type: string time: description: The time commenting the alarm type: string format: date-time userIdentifier: description: The user commenting the alarm type: string Error: description: > Standard Class used to describe API response error Not intended to be used directly. The `code` in the HTTP header is used as a discriminator for the type of error returned in runtime. type: object properties: message: description: >- Text that provides mode details and corrective actions related to the error. This can be shown to a client user. type: string reason: description: >- Text that explains the reason for the error. This can be shown to a client user. type: string maxLength: 255 referenceError: description: URL pointing to documentation describing the error type: string format: uri required: - reason Error400: description: Bad Request. (https://tools.ietf.org/html/rfc7231#section-6.5.1) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: | One of the following error codes: - missingQueryParameter: The URI is missing a required query-string parameter - missingQueryValue: The URI is missing a required query-string parameter value - invalidQuery: The query section of the URI is invalid. - invalidBody: The request has an invalid body $ref: '#/components/schemas/Error400Code' required: - code Error400Code: description: | One of the following error codes: - missingQueryParameter: The URI is missing a required query-string parameter - missingQueryValue: The URI is missing a required query-string parameter value - invalidQuery: The query section of the URI is invalid. - invalidBody: The request has an invalid body type: string enum: - missingQueryParameter - missingQueryValue - invalidQuery - invalidBody Error401: description: Unauthorized. (https://tools.ietf.org/html/rfc7235#section-3.1) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: | One of the following error codes: - missingCredentials: No credentials provided. - invalidCredentials: Provided credentials are invalid or expired $ref: '#/components/schemas/Error401Code' required: - code Error401Code: description: | One of the following error codes: - missingCredentials: No credentials provided. - invalidCredentials: Provided credentials are invalid or expired type: string enum: - missingCredentials - invalidCredentials Error403: description: >- Forbidden. This code indicates that the server understood the request but refuses to authorize it. (https://tools.ietf.org/html/rfc7231#section-6.5.3) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: |- This code indicates that the server understood the request but refuses to authorize it because of one of the following error codes: - accessDenied: Access denied - forbiddenRequester: Forbidden requester - tooManyUsers: Too many users $ref: '#/components/schemas/Error403Code' required: - code Error403Code: description: |- This code indicates that the server understood the request but refuses to authorize it because of one of the following error codes: - accessDenied: Access denied - forbiddenRequester: Forbidden requester - tooManyUsers: Too many users type: string enum: - accessDenied - forbiddenRequester - tooManyUsers Error404: description: >- Resource for the requested path not found. (https://tools.ietf.org/html/rfc7231#section-6.5.4) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: | The following error code: - notFound: A current representation for the target resource not found type: string enum: - notFound required: - code Error409: description: Conflict (https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.8) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: | The following error code: - conflict: The client has provided a value whose semantics are not appropriate for the property. type: string enum: - conflict required: - code Error422: description: >- Unprocessable entity due to a business validation problem. (https://tools.ietf.org/html/rfc4918#section-11.2) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: | One of the following error codes: - missingProperty: The property the Seller has expected is not present in the payload - invalidValue: The property has an incorrect value - invalidFormat: The property value does not comply with the expected value format - referenceNotFound: The object referenced by the property cannot be identified in the Seller system - unexpectedProperty: Additional property, not expected by the Seller has been provided - tooManyRecords: the number of records to be provided in the response exceeds the Seller's threshold. - otherIssue: Other problem was identified (detailed information provided in a reason) $ref: '#/components/schemas/Error422Code' propertyPath: description: > A pointer to a particular property of the payload that caused the validation issue. It is highly recommended that this property should be used. Defined using JavaScript Object Notation (JSON) Pointer (https://tools.ietf.org/html/rfc6901). type: string required: - code Error422Code: description: | One of the following error codes: - missingProperty: The property the Seller has expected is not present in the payload - invalidValue: The property has an incorrect value - invalidFormat: The property value does not comply with the expected value format - referenceNotFound: The object referenced by the property cannot be identified in the Seller system - unexpectedProperty: Additional property, not expected by the Seller has been provided - tooManyRecords: the number of records to be provided in the response exceeds the Seller's threshold. - otherIssue: Other problem was identified (detailed information provided in a reason) type: string enum: - missingProperty - invalidValue - invalidFormat - referenceNotFound - unexpectedProperty - tooManyRecords - otherIssue Error500: description: >- Internal Server Error. (https://tools.ietf.org/html/rfc7231#section-6.6.1) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: | The following error code: - internalError: Internal server error - the server encountered an unexpected condition that prevented it from fulfilling the request. type: string enum: - internalError required: - code Error501: description: >- Not Implemented. Used in case Seller is not supporting an optional operation (https://tools.ietf.org/html/rfc7231#section-6.6.2) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: |- The following error code: - notImplemented: Method not supported by the server type: string enum: - notImplemented required: - code EventSubscription: required: - id allOf: - $ref: '#/components/schemas/EventSubscriptionInput' - description: This resource is used to respond to notification subscriptions. type: object properties: id: description: >- An identifier of this Event Subscription assigned when a resource is created. type: string EventSubscriptionInput: description: This class is used to register for Notifications. type: object properties: callback: description: >- This callback value must be set to *host* property from Alarm Notification API (alarmNotification.api.yaml). This property is appended with the base path and notification resource path specified in that API to construct an URL to which notification is sent. E.g. for 'callback': "https://buyer.mplify.com/listenerEndpoint", the alarm event notification will be sent to: `https://buyer.mplify.com/listenerEndpoint/mefApi/legato/alarmNotification/v2/listener/` type: string query: description: >- This attribute is used to define which type of events to register to. Example: 'query':'eventType = createAlarm'. To subscribe for more than one event type, put the values separated by a comma: `eventType=alarmCreateEvent, alarmAttributeValueChangeEvent`. The possible values are enumerated by Event type enums in alarmNotification.api.yaml. An empty query is treated as specifying no filters - ending in subscription for all event types. type: string required: - callback PerceivedSeverity: description: |- List of possible severities that can be allocated to an Alarm. The values are consistent with ITU - T Recommendation X.733. Once an alarm has been cleared, its perceived severity is set to 'cleared' and can no longer be set. | state | Mplify 133.1 name | Description | | --------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cleared` | Cleared | The Cleared severity level indicates the clearing of one or more previously reported alarms. | | `critical` | Critical | The Critical severity level indicates that a service affecting condition has occurred and an immediate corrective action is required. | | `indeterminate` | Indeterminate | The Indeterminate severity level indicates that the severity level cannot be determined. | | `major` | Major | The Major severity level indicates that a service affecting condition has developed and an urgent corrective action is required. | | `minor` | Minor | The Minor severity level indicates the existence of a non-service affecting fault condition and that corrective action should be taken in order to prevent a more serious (for example, service affecting) fault.| | `warning` | Warning | The Warning severity level indicates the detection of a potential or impending service affecting fault, before any significant effects have been felt. | type: string enum: - cleared - critical - indeterminate - major - minor - warning PlannedOutageIndicator: description: >- Indicates that the Managed Object (related to this alarm) is in in planned maintenance, or out of service. type: string enum: - inPlannedMaintenance - outOfService ProbableCause: description: >- list of alarm probable cause as defined in ITU - T Recommendation X.733 or 3GPP TS 32.111 - 2 Annex B. type: string enum: - adapterError - applicationSubsystemFailure - bandwidthReduced - callEstablishmentError - communicationsProtocolError - communicationsSubsystemFailure - configurationOrCustomizationError - congestion - corruptData - cpuCyclesLimitExceeded - datasetOrModemError - degradedSignal - dteDceInterfaceError - enclosureDoorOpen - equipmentMalfunction - excessiveVibration - fileError - fireDetected - floodDetected - framingError - heatingVentilationCoolingSystemProblem - humidityUnacceptable - ioDeviceError - inputDeviceError - lanError - leakDetected - localNodeTransmissionError - lossOfFrame - lossOfSignal - materialSupplyExhausted - multiplexerProblem - outOfMemory - outputDeviceError - performanceDegraded - powerProblem - pressureUnacceptable - processorProblem - pumpFailure - queueSizeExceeded - receiveFailure - receiverFailure - remoteNodeTransmissionError - resourceNearingCapacity - responseTimeExcessive - retransmissionRateExcessive - softwareError - softwareProgramTerminated - softwareProgramError - storageCapacityProblem - temperatureUnacceptable - thresholdCrossed - timingProblem - toxicLeakDetected - transmitFailure - transmitterFailure - underlyingResourceUnavailable - versionMismatch ServiceRef: description: Reference to a Service instance. type: object properties: href: description: Hyperlink reference to Service type: string id: description: unique identifier of Service type: string required: - id