module ietf-alarms-x733 {

    yang-version 1.1;

    namespace
      "urn:ietf:params:xml:ns:yang:ietf-alarms-x733";

    prefix x733;

    import ietf-alarms {
      prefix al;
    }
    import ietf-yang-types {
      prefix yang;
      reference
        "RFC 6991: Common YANG Data Types";


    }

    organization "IETF CCAMP Working Group";

    contact
      "WG Web:   <https://trac.ietf.org/trac/ccamp>
     WG List:  <mailto:ccamp@ietf.org>

     Editor:   Stefan Vallin
               <mailto:stefan@wallan.se>

     Editor:   Martin Bjorklund
               <mailto:mbj@tail-f.com>";

    description
      "This module augments the ietf-alarms module with X.733 alarm
     parameters.

     The following structures are augmented with the X.733 event type
     and probable cause:

      1) alarms/alarm-inventory: all possible alarm types
      2) alarms/alarm-list: every alarm in the system
      3) alarm-notification: notifications indicating alarm-state
         changes
      4) alarms/shelved-alarms

     The module also optionally allows the alarm-management system
     to configure the mapping from the ietf-alarms' alarm keys
     to the ITU tuple (event-type, probable-cause).

     The mapping does not include a corresponding problem value
     specific to X.733.  The recommendation is to use the
     'alarm-type-qualifier' leaf, which serves the same purpose.

     The module uses an integer and a corresponding string for
     probable cause instead of a globally defined enumeration, in
     order to be able to manage conflicting enumeration definitions.
     A single globally defined enumeration is challenging to
     maintain.

     The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
     NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
     'MAY', and 'OPTIONAL' in this document are to be interpreted as
     described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
     they appear in all capitals, as shown here.

     Copyright (c) 2019 IETF Trust and the persons identified as
     authors of the code.  All rights reserved.

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject to
     the license terms contained in, the Simplified BSD License set
     forth in Section 4.c of the IETF Trust's Legal Provisions
     Relating to IETF Documents
     (https://trustee.ietf.org/license-info).

     This version of this YANG module is part of RFC 8632; see
     the RFC itself for full legal notices.";

    reference
      "ITU-T Recommendation X.733: Information Technology
        - Open Systems Interconnection
        - System Management: Alarm Reporting Function";


    revision "2019-09-11" {
      description "Initial revision.";
      reference
        "RFC 8632: A YANG Data Model for Alarm Management";

    }


    feature configure-x733-mapping {
      description
        "The system supports configurable X733 mapping from
       the ietf-alarms' alarm-type to X733 event-type
       and probable-cause.";
    }

    typedef event-type {
      type enumeration {
        enum "other" {
          value 1;
          description "None of the below.";
        }
        enum "communications-alarm" {
          value 2;
          description
            "An alarm of this type is principally associated with the
           procedures and/or processes required to convey
           information from one point to another.";
        }
        enum "quality-of-service-alarm" {
          value 3;
          description
            "An alarm of this type is principally associated with a
           degradation in the quality of a service.";
        }
        enum "processing-error-alarm" {
          value 4;
          description
            "An alarm of this type is principally associated with a
           software or processing fault.";
        }
        enum "equipment-alarm" {
          value 5;
          description
            "An alarm of this type is principally associated with an
           equipment fault.";
        }
        enum "environmental-alarm" {
          value 6;
          description
            "An alarm of this type is principally associated with a
           condition relating to an enclosure in which the equipment
           resides.";
        }
        enum "integrity-violation" {
          value 7;
          description
            "An indication that information may have been illegally
           modified, inserted, or deleted.";
        }
        enum "operational-violation" {
          value 8;
          description
            "An indication that the provision of the requested service
           was not possible due to the unavailability, malfunction,
           or incorrect invocation of the service.";
        }
        enum "physical-violation" {
          value 9;
          description
            "An indication that a physical resource has been violated
           in a way that suggests a security attack.";
        }
        enum
          "security-service-or-mechanism-violation" {
          value 10;
          description
            "An indication that a security attack has been detected by
           a security service or mechanism.";
        }
        enum "time-domain-violation" {
          value 11;
          description
            "An indication that an event has occurred at an unexpected
           or prohibited time.";
        }
      }
      description
        "The event types as defined by X.733 and X.736.";
      reference
        "ITU-T Recommendation X.733: Information Technology
          - Open Systems Interconnection
          - System Management: Alarm Reporting Function
        ITU-T Recommendation X.736: Information Technology
          - Open Systems Interconnection
          - System Management: Security Alarm Reporting Function";

    }

    typedef trend {
      type enumeration {
        enum "less-severe" {
          value 0;
          description
            "There is at least one outstanding alarm of a
           severity higher (more severe) than that in the
           current alarm.";
        }
        enum "no-change" {
          value 1;
          description
            "The Perceived severity reported in the current
           alarm is the same as the highest (most severe)
           of any of the outstanding alarms";
        }
        enum "more-severe" {
          value 2;
          description
            "The Perceived severity in the current alarm is
           higher (more severe) than that reported in any
           of the outstanding alarms.";
        }
      }
      description
        "This type is used to describe the
       severity trend of the alarming resource.";
      reference
        "ITU-T Recommendation X.721: Information Technology
           - Open Systems Interconnection
           - Structure of management information:
             Definition of management information
             Module Attribute-ASN1Module";

    }

    typedef value-type {
      type union {
        type int64;
        type uint64;
        type decimal64 {
          fraction-digits 2;
        }
      }
      description
        "A generic union type to match the ITU choice of
       integer and real.";
    }

    grouping x733-alarm-parameters {
      description
        "Common X.733 parameters for alarms.";
      reference
        "ITU-T Recommendation X.733: Information Technology
          - Open Systems Interconnection
          - System Management: Alarm Reporting Function
        ITU-T Recommendation X.736: Information Technology
          - Open Systems Interconnection
          - System Management: Security Alarm Reporting Function";

      leaf event-type {
        type event-type;
        description
          "The X.733/X.736 event type for this alarm.";
      }

      leaf probable-cause {
        type uint32;
        description
          "The X.733 probable cause for this alarm.";
      }

      leaf probable-cause-string {
        type string;
        description
          "The user-friendly string matching
         the probable cause integer value.  The string
         SHOULD match the X.733 enumeration.  For example,
         value 27 is 'localNodeTransmissionError'.";
      }

      container threshold-information {
        description
          "This parameter shall be present when the alarm
         is a result of crossing a threshold. ";
        leaf triggered-threshold {
          type string;
          description
            "The identifier of the threshold attribute that
           caused the notification.";
        }

        leaf observed-value {
          type value-type;
          description
            "The value of the gauge or counter that crossed
           the threshold.  This may be different from the
           threshold value if, for example, the gauge may
           only take on discrete values.";
        }

        choice threshold-level {
          description
            "In the case of a gauge, the threshold level specifies
           a pair of threshold values: the first is the value
           of the crossed threshold, and the second is its
           corresponding hysteresis; in the case of a counter,
           the threshold level specifies only the threshold
           value.";
          case up {
            leaf up-high {
              type value-type;
              description
                "The going-up threshold for raising the alarm.";
            }

            leaf up-low {
              type value-type;
              description
                "The going-down threshold for clearing the alarm.
               This is used for hysteresis functions for gauges.";
            }
          }  // case up

          case down {
            leaf down-low {
              type value-type;
              description
                "The going-down threshold for raising the alarm.";
            }

            leaf down-high {
              type value-type;
              description
                "The going-up threshold for clearing the alarm.
               This is used for hysteresis functions for gauges.";
            }
          }  // case down
        }  // choice threshold-level

        leaf arm-time {
          type yang:date-and-time;
          description
            "For a gauge threshold, it's the time at which the
           threshold was last re-armed; namely, it's the time after
           the previous threshold crossing at which the hysteresis
           value of the threshold was exceeded, thus again permitting
           the generation of notifications when the threshold is
           crossed.  For a counter threshold, it's the later of the
           time at which the threshold offset was last applied or the
           counter was last initialized (for resettable counters).";
        }
      }  // container threshold-information

      list monitored-attributes {
        key "id";
        description
          "The Monitored attributes parameter, when present, defines
         one or more attributes of the resource and their
         corresponding values at the time of the alarm.";
        uses attribute;
      }  // list monitored-attributes

      leaf-list proposed-repair-actions {
        type string;
        description
          "This parameter, when present, is used if the cause is
         known and the system being managed can suggest one or
         more solutions (such as switch in standby equipment,
         retry, and replace media).";
      }

      leaf trend-indication {
        type trend;
        description
          "This parameter specifies the current severity
         trend of the resource.  If present, it indicates
         that there are one or more alarms ('outstanding
         alarms') that have not been cleared and that
         pertain to the same resource as this alarm
         ('current alarm') does.  The possible values are:

           more-severe: The Perceived severity in the current
             alarm is higher (more severe) than that reported in
             any of the outstanding alarms.

           no-change: The Perceived severity reported in the
             current alarm is the same as the highest (most severe)
             of any of the outstanding alarms.

           less-severe: There is at least one outstanding alarm
             of a severity higher (more severe) than that in the
             current alarm.";
      }

      leaf backedup-status {
        type boolean;
        description
          "This parameter, when present, specifies whether or not the
         object emitting the alarm has been backed up; therefore, it
         is possible to know whether or not services provided to the
         user have been disrupted when this parameter is included.
         The use of this field in conjunction with the
         'perceived-severity' field provides information in an
         independent form to qualify the seriousness of the alarm and
         the ability of the system as a whole to continue to provide
         services.  If the value of this parameter is true, it
         indicates that the object emitting the alarm has been backed
         up; if false, the object has not been backed up.";
      }

      leaf backup-object {
        type al:resource;
        description
          "This parameter SHALL be present when the 'backedup-status'
         parameter is present and has the value 'true'.  This
         parameter specifies the managed object instance that is
         providing back-up services for the managed object to which
         the notification pertains.  This parameter is useful, for
         example, when the back-up object is from a pool of objects,
         any of which may be dynamically allocated to replace a
         faulty object.";
      }

      list additional-information {
        key "identifier";
        description
          "This parameter allows the inclusion of an additional
         information set in the alarm.  It is a series of data
         structures, each of which contains three items of
         information: an identifier, a significance indicator,
         and the problem information.";
        leaf identifier {
          type string;
          description
            "Identifies the data type of the information parameter.";
        }

        leaf significant {
          type boolean;
          description
            "Set to 'true' if the receiving system must be able to
           parse the contents of the information subparameter
           for the event report to be fully understood.";
        }

        leaf information {
          type string;
          description
            "Additional information about the alarm.";
        }
      }  // list additional-information

      leaf security-alarm-detector {
        type al:resource;
        description
          "This parameter identifies the detector of the security
         alarm.";
      }

      leaf service-user {
        type al:resource;
        description
          "This parameter identifies the service-user whose request
         for service led to the generation of the security alarm.";
      }

      leaf service-provider {
        type al:resource;
        description
          "This parameter identifies the intended service-provider
         of the service that led to the generation of the security
         alarm.";
      }
    }  // grouping x733-alarm-parameters

    grouping x733-alarm-definition-parameters {
      description
        "Common X.733 parameters for alarm definitions.
       This grouping is used to define those alarm
       attributes that can be mapped from the alarm-type
       mechanism in the ietf-alarms module.";
      leaf event-type {
        type event-type;
        description
          "The alarm type has this X.733/X.736 event type.";
      }

      leaf probable-cause {
        type uint32;
        description
          "The alarm type has this X.733 probable cause value.
         This module defines probable cause as an integer
         and not as an enumeration.  The reason being that the
         primary use of probable cause is in the management
         application if it is based on the X.733 standard.
         However, most management applications have their own
         defined enum definitions and merging enums from
         different systems might create conflicts.  By using
         a configurable uint32, the system can be configured
         to match the enum values in the management application.";
      }

      leaf probable-cause-string {
        type string;
        description
          "This string can be used to give a user-friendly string
         to the probable cause value.";
      }
    }  // grouping x733-alarm-definition-parameters

    grouping attribute {
      description
        "A grouping to match the ITU generic reference to
       an attribute.";
      reference
        "ITU-T Recommendation X.721: Information Technology
           - Open Systems Interconnection
           - Structure of management information:
             Definition of management information
        Module Attribute-ASN1Module";

      leaf id {
        type al:resource;
        description
          "The resource representing the attribute.";
      }

      leaf value {
        type string;
        description
          "The value represented as a string since it could
         be of any type.";
      }
    }  // grouping attribute

    augment /al:alarms/al:alarm-inventory/al:alarm-type {
      description
        "Augment X.733 mapping information to the alarm inventory.";
      uses x733-alarm-definition-parameters;
    }

    augment /al:alarms/al:control {
      description
        "Add X.733 mapping capabilities. ";
      list x733-mapping {
        if-feature configure-x733-mapping;
        key "alarm-type-id alarm-type-qualifier-match";
        description
          "This list allows a management application to control the
         X.733 mapping for all alarm types in the system.  Any entry
         in this list will allow the alarm manager to override the
         default X.733 mapping in the system, and the final mapping
         will be shown in the alarm inventory.";
        leaf alarm-type-id {
          type al:alarm-type-id;
          description
            "Map the alarm type with this alarm type identifier.";
        }

        leaf alarm-type-qualifier-match {
          type string;
          description
            "A W3C regular expression that is used when mapping an
           alarm type and alarm-type-qualifier to X.733 parameters.";
        }

        uses x733-alarm-definition-parameters;
      }  // list x733-mapping
    }

    augment /al:alarms/al:alarm-list/al:alarm {
      description
        "Augment X.733 information to the alarm.";
      uses x733-alarm-parameters;
    }

    augment /al:alarms/al:shelved-alarms/al:shelved-alarm {
      description
        "Augment X.733 information to the alarm.";
      uses x733-alarm-parameters;
    }

    augment /al:alarm-notification {
      description
        "Augment X.733 information to the alarm notification.";
      uses x733-alarm-parameters;
    }
  }  // module ietf-alarms-x733