MEF LSO Legato Alarm Management

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 prov

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mef/refs/heads/main/openapi/mef-lso-legato-alarm-management-openapi.yml