module ietf-alarms {

    yang-version 1;

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

    prefix alarms;

    import ietf-yang-types {
      prefix yang;
    }

    organization
      "IETF NETMOD (NETCONF Data Modeling Language) Working Group";

    contact
      "WG Web:   <http://tools.ietf.org/wg/netmod/>
WG List:  <mailto:netmod@ietf.org>

WG Chair: Thomas Nadeau
	  <mailto:tnadeau@lucidvision.com>

WG Chair: Juergen Schoenwaelder
	  <mailto:j.schoenwaelder@jacobs-university.de>

Editor:   Stefan Vallin
	  <mailto:svallin@cisco.com>

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

    description
      "This module is an interface for managing alarms.  Main inputs to
the module design are the 3GPP Alarm IRP and ITU-T X.733 alarm
standards.  Main features:
* alarm list: a list of all alarms.  Cleared alarms stay in the
  list until explicitly removed.
* operator actions on alarms: acknowledging and closing alarms.
* administrative actions on alarms: purging alarms from the list
  according to specific criteria.
* alarm inventory: a management application can read all
  alarm types implemented by the system.
* alarm shelving: shelving (blocking) alarms according
  to specific criteria.

This module uses a stateful view on alarms.  An alarm is a state
for a specific resource.  An alarm type is a possible alarm
state for a resource.  For example, the tuple ('linkAlarm',
'GigabitEthernet0/25') is an alarm of type 'linkAlarm' on the
resource 'GigabitEthernet0/25'.

Alarm types are identified using YANG identities and an optional
string-based qualifier.  The string-based qualifier allows for
dynamic extension of the statically defined alarm types.  Alarm
types identifies a possible alarm state and not the individual
notifications. 'linkDown' and 'linkUp' notifications are two
notifications refering to the same alarm type 'linkAlarm'.

In this way there is no ambiguity about how alarm and alarm
clear correlation should be performed: notifications reporting
the same resource, and alarm type are considered updates of the
same alarm, such as clearing an active alarm or changing the
severity of an active alarm.

Severity and alarm text can be changed on an existing alarm.
The above alarm example can therefore look like: (('linkAlarm',
'GigabitEthernet0/25'), warning, 'interface down while interface
admin state is ip')

There is a clear separation between updates on the alarm from
the underlying resource, like clear, and updates from an
operator like acknowledge or closing an alarm: (('linkAlarm',
'GigabitEthernet0/25'), warning, 'interface down while interface
admin state is ip', cleared, closed)

Administrative actions like removing closed alarms older than a
given time is supported.";

    revision "2015-05-04" {
      description "Initial revision.";
      reference
        "RFC XXXX: YANG Alarm Module";

    }


    feature operator-actions {
      description
        "This feature means that the systems supports operator states
on alarms.";
    }

    feature alarm-shelving {
      description
        "This feature means that the systems shelf (filter) alarms.";
    }

    identity alarm-identity {
      description
        "Base identity for alarm types.  A unique identification of the
alarm, not including the resource.  Different resources can
share alarm types.  If the resource reports the same alarm
type, it is to be considered to be the same alarm.  The alarm
type is a simplification of the different X.733 and 3GPP alarm
IRP alarm correlation mechanisms and it allows for
hierarchical extensions.

A string-based qualifier can be used in addition to the
identity in order to have different alarm types based on
information not known at design-time, such as values in
textual SNMP Notification var-binds.

Standards and vendors can define sub-identities to clearly
identify specific alarm types.

This identity is abstract and shall not be used for alarms.";
    }

    typedef resource {
      type union {
        type instance-identifier;
        type yang:object-identifier;
        type string;
      }
      description
        "If the alarming resource is modelled in YANG, this type
will be an instance-identifier.  If the resource is an SNMP
object, the type will be an object-identifier.  If the
resource is anything else, for example a distinguished
name or a CIM path, this type will be a string.";
    }

    typedef alarm-text {
      type string {
        length "1..1024";
      }
      description
        "The string used to inform operators about the alarm.  This
MUST contain enough information for an operator to be able
to understand the problem and how to resolve it.  If this
string contains structure, this format should be clearly
documented for programs to be able to parse that
information.";
    }

    typedef severity {
      type enumeration {
        enum "indeterminate" {
          value 2;
          description
            "Indicates that the severity level could not be
determined. This level SHOULD be avoided.";
        }
        enum "minor" {
          value 3;
          description
            "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. Such a severity
can be reported, for example, when the detected alarm
condition is not currently degrading the capacity of the
resource.";
        }
        enum "warning" {
          value 4;
          description
            "The 'warning' severity level indicates the detection of
a potential or impending service affecting fault, before
any significant effects have been felt. Action should be
taken to further diagnose (if necessary) and correct the
problem in order to prevent it from becoming a more
serious service affecting fault.";
        }
        enum "major" {
          value 5;
          description
            "The 'major' severity level indicates that a service
affecting condition has developed and an urgent
corrective action is required. Such a severity can be
reported, for example, when there is a severe
degradation in the capability of the resource
and its full capability must be restored.";
        }
        enum "critical" {
          value 6;
          description
            "The 'critical' severity level indicates that a service
affecting condition has occurred and an immediate
corrective action is required. Such a severity can be
reported, for example, when a resource becomes totally
out of service and its capability must be restored.";
        }
      }
      description
        "The severity level of the alarm.";
      reference
        "ITU Recommendation X.733, 'Information Technology - Open
          Systems Interconnection - System Management: Alarm Reporting
          Function', 1992";

    }

    typedef severity-with-clear {
      type union {
        type enumeration {
          enum "cleared" {
            value 1;
            description
              "The alarm is cleared by the instrumentation.";
          }
        }
        type severity;
      }
      description
        "The severity level of the alarm including clear.
This is used only in state changes for an alarm.";
    }

    typedef operator-state {
      type enumeration {
        enum "none" {
          value 1;
          description
            "The alarm is not being taken care of.";
        }
        enum "ack" {
          value 2;
          description
            "The alarm is being taken care of.  Corrective action not
taken yet, or failed";
        }
        enum "closed" {
          value 3;
          description
            "Corrective action taken successfully.";
        }
      }
      description
        "Operator states on an alarm.  The 'closed' state indicates
that an operator considers the alarm being resolved.  This
is separate from the resource alarm clear flag.";
    }

    typedef alarm-type-id {
      type identityref {
        base alarm-identity;
      }
      description
        "Identifies an alarm type. The description of the alarm type id
MUST indicate if the alarm type is abstract or not. An
abstract alarm type is used as a base for other alarm type ids
and will not be used as a value for an alarm or be present in
the alarm inventory.";
    }

    typedef alarm-type-qualifier {
      type string;
      description
        "If an alarm type can not be fully specified at design-time by
alarm-type-id, this string qualifier is used in addition to
fully define a unique alarm type.
The configuration of alarm qualifiers is considered being part
of the instrumentation and out of scope for this module.";
    }

    grouping common-alarm-parameters {
      description
        "Common parameters for an alarm.

This grouping is used both in the alarm list and in the
notification representing an alarm state change.";
      leaf resource {
        type resource;
        mandatory true;
        description
          "The alarming resource.  See also 'alt-resource'.";
      }

      leaf alarm-type-id {
        type alarm-type-id;
        mandatory true;
        description
          "This leaf and the leaf 'alarm-type-qualifier' together
provides a unique identification of the alarm type.";
      }

      leaf alarm-type-qualifier {
        type alarm-type-qualifier;
        description
          "This leaf is used when the 'alarm-type-id' leaf cannot
uniquely identify the alarm type.  Normally, this is not
the case, and this leaf is the empty string.";
      }

      leaf-list alt-resource {
        type resource;
        description
          "Used if the alarming resource is available over other
interfaces.  This field can contain SNMP OID's, CIM paths or
3GPP Distinguished names for example.";
      }

      list related-alarms {
        description
          "References to related alarms.  The reference is expressed as
values for the alarm list and not leafrefs since the related
alarm might have been removed from the alarm list.";
        leaf resource {
          type resource;
          description
            "The alarming resource for the related alarm.";
        }

        leaf alarm-type-id {
          type alarm-type-id;
          description
            "The alarm type identifier for the related alarm.";
        }

        leaf alarm-type-qualifier {
          type alarm-type-qualifier;
          description
            "The optional alarm qualifier for the related alarm.";
        }
      }  // list related-alarms

      leaf-list impacted-resources {
        type resource;
        description
          "Resources that might be affected by this alarm.";
      }

      leaf-list root-cause-resources {
        type resource;
        description
          "Resources that are candidates for causing the alarm.";
      }
    }  // grouping common-alarm-parameters

    grouping alarm-status-change-parameters {
      description
        "Parameters for an alarm state change.

This grouping is used both in the alarm list's
status-change list and in the notification representing an
alarm state change.";
      leaf event-time {
        type yang:date-and-time;
        mandatory true;
        description
          "The time the status of the alarm changed.  The value
represents the time the real alarm state change appeared
in the resource and not when it was added to the
alarm list.";
      }

      leaf perceived-severity {
        type severity-with-clear;
        mandatory true;
        description
          "The severity of the alarm as defined by X.733.  Note
that this may not be the original severity since the alarm
may have changed severity.";
        reference
          "ITU Recommendation X.733, 'Information Technology - Open
          Systems Interconnection - System Management: Alarm Reporting
          Function', 1992";

      }

      leaf alarm-text {
        type alarm-text;
        mandatory true;
        description
          "A user friendly text describing the alarm state change.";
        reference
          "Additional Text from ITU Recommendation X.733, 'Information
           Technology
           - Open Systems Interconnection - System Management: Alarm
           Reporting Function', 1992";

      }
    }  // grouping alarm-status-change-parameters

    grouping operator-parameters {
      description
        "This grouping defines parameters that can
be changed by an operator";
      leaf time {
        type yang:date-and-time;
        mandatory true;
        description
          "Timestamp for operator action on alarm.";
      }

      leaf state {
        type operator-state;
        mandatory true;
        description
          "The operator's view of the alarm state.";
      }

      leaf operator {
        type string;
        mandatory true;
        description
          "The name of the operator that has acted on this
alarm.";
      }

      leaf text {
        type string;
        description
          "Additional optional textual information provided by
the operator.";
      }
    }  // grouping operator-parameters

    container alarms {
      description
        "The top container for this module";
      container control {
        description
          "Configuration to control the alarm behaviour.";
        leaf max-alarm-history {
          type uint16;
          default "32";
          description
            "The status-change entries are kept in a circular list.
When this number is exceeded, the oldest status change
entry is automatically removed.  If the value is 0, the
status change entries are accumulated indefinitely.";
        }

        leaf notify-status-changes {
          type boolean;
          default "false";
          description
            "This leaf controls whether notifications are sent on all
alarm status updates, e.g., updated perceived-severity or
alarm-text.  By default the notifications are only sent
when a new alarm is raised, re-raised after being cleared
and when an alarm is cleared.";
        }

        container shelved-alarms {
          if-feature alarm-shelving;
          description
            "This list is used to shelf alarms.  The server will stop
updating the alarm list and sending notifications for the
shelved alarms.  Any alarms corresponding to the shelving
criteria stays in the alarm list. When a shelved alarm is
deleted or changed, the server SHOULD update the alarm
list to the current state.";
          list shelved-alarm {
            key "shelf-name";
            description
              "Each entry defines the criteria for shelving alarms.";
            leaf shelf-name {
              type string;
              description
                "A description of the shelved alarm. It SHOULD include
the reason for shelving this alarm";
            }

            leaf resource {
              type resource;
              description
                "Shelv alarms for this resource.";
            }

            leaf alarm-type-id {
              type alarm-type-id;
              description
                "Shelv alarms for this alarm type identifier.";
            }

            leaf alarm-type-qualifier {
              type alarm-type-qualifier;
              description
                "Shelv alarms for this alarm type qualifier.";
            }
          }  // list shelved-alarm
        }  // container shelved-alarms
      }  // container control

      container alarm-inventory {
        config false;
        description
          "This list contains all possible alarm types for the system.
The list also tells if each alarm type has a corresponding
clear state. The inventory shall only contain concrete alarm
types.";
        list alarm-type {
          description
            "An entry in this list defines a possible alarm.";
          leaf alarm-type-id {
            type alarm-type-id;
            mandatory true;
            description
              "The statically defined alarm type identifier for this
possible alarm.";
          }

          leaf alarm-type-qualifier {
            type alarm-type-qualifier;
            description
              "The optionally dynamically defined alarm type identifier
for this possible alarm.";
          }

          leaf has-clear {
            type union {
              type boolean;
            }
            mandatory true;
            description
              "This leaf tells the operator if the alarm will be
cleared when the correct corrective action has been
taken.  Implementations SHOULD strive for detecting the
cleared state for all alarm types.  If this leaf is
true, the operator can monitor the alarm until it
becomes cleared after the corrective action has been
taken.  If this leaf is false the operator needs to
validate that the alarm is not longer active using other
mechanisms.  Alarms can lack a corresponding clear due
to missing instrumentation or that there is no logical
corresponding clear state.";
          }

          leaf description {
            type string;
            mandatory true;
            description
              "A description of the possible alarm.  It SHOULD include
information on possible underlying root causes and
corrective actions.";
          }
        }  // list alarm-type
      }  // container alarm-inventory

      list summary {
        key "severity";
        config false;
        description
          "A global summary of all alarms in the system.";
        leaf severity {
          type severity;
          description
            "Alarm summary for this severity level.";
        }

        leaf total {
          type yang:gauge32;
          description
            "Total number of alarms of this severity level.";
        }

        leaf cleared {
          type yang:gauge32;
          description
            "For this severity level, the number of alarms that are
cleared.";
        }

        leaf cleared-not-closed {
          if-feature operator-actions;
          type yang:gauge32;
          description
            "For this severity level, the number of alarms that are
cleared but not closed.";
        }

        leaf cleared-closed {
          if-feature operator-actions;
          type yang:gauge32;
          description
            "For this severity level, the number of alarms that are
cleared and closed.";
        }

        leaf not-cleared-closed {
          if-feature operator-actions;
          type yang:gauge32;
          description
            "For this severity level, the number of alarms that are
not cleared but closed.";
        }

        leaf not-cleared-not-closed {
          if-feature operator-actions;
          type yang:gauge32;
          description
            "For this severity level, the number of alarms that are
not cleared and not closed.";
        }
      }  // list summary

      container alarm-list {
        config false;
        description
          "The alarms in the system.";
        leaf number-of-alarms {
          type yang:gauge32;
          description
            "This object shows the total number of currently
alarms, i.e., the total number of entries
in the alarm list.";
        }

        leaf last-changed {
          type yang:date-and-time;
          description
            "A timestamp when the active alarm list was last
changed. The value can be used by a manager to
initiate an alarm resynchronization procedure.";
        }

        list alarm {
          key "resource alarm-type-id alarm-type-qualifier";
          description
            "The list of alarms.  Each entry in the list holds one
alarm for a given alarm type and device, managed object.
An alarm can be updated from the underlying device or
by the user. These changes are reflected in different
lists below the corresponding alarm.";
          uses common-alarm-parameters;

          leaf is-cleared {
            type boolean;
            mandatory true;
            description
              "Indicates the clearance state of the alarm.  An alarm
might toggle from active alarm to cleared alarm and back
to active again.  This leaf reflects the perceived
severity in the latest entry in the status-change
list.";
          }

          leaf last-status-change {
            type yang:date-and-time;
            mandatory true;
            description
              "A timestamp when the status-change list was last
changed. This value equals the latest 'when' leaf in the
status-change list.  The value can be used by a manager
to read the last status change without iterating the
status-change list below.";
          }

          leaf last-perceived-severity {
            type severity;
            mandatory true;
            description
              "The severity of the last status-change that
reported a severity that is not equal to cleared.";
          }

          leaf last-alarm-text {
            type alarm-text;
            mandatory true;
            description
              "The alarm-text of the last status-change that
reported a severity that is not equal to cleared.";
          }

          list status-change {
            key "event-time";
            min-elements 1;
            description
              "A list of status change events for this alarm.

This list is ordered according to the timestamps of
alarm state changes. The last item corresponds to the
latest state change.

The following state changes creates an entry in this
list:
- changed severity (warning, minor, major, critical)
- clearance status, this also updates the is-cleared
  leaf
- alarm text update";
            uses alarm-status-change-parameters;
          }  // list status-change

          leaf last-operator-state {
            if-feature operator-actions;
            type operator-state;
            mandatory true;
            description
              "The state of the alarm as set by the operator. When the
alarm is first raised by the instrumentation it has the
'none' state. After initial alarm raise this leaf
represents the state in the latest entry in the
'operator-action' list.
The 'closed' state indicates that the alarm is
considered resolved by the operator.";
          }

          leaf last-operator {
            if-feature operator-actions;
            type string;
            description
              "The last operator that acted upon the alarm.";
          }

          leaf last-operator-text {
            if-feature operator-actions;
            type alarm-text;
            description
              "The alarm-text of the last status-change that
reported a severity that is not equal to cleared.";
          }

          leaf last-operator-action {
            if-feature operator-actions;
            type yang:date-and-time;
            description
              "A timestamp when the operator-change list was last
changed.";
          }

          list operator-action {
            if-feature operator-actions;
            key "time";
            description
              "This list is used by operators to indicate
the state of human intervention on an alarm.
For example, if an operator has seen an alarm,
the operator can add a new item to this list indicating
that the alarm is acknowledged.";
            uses operator-parameters;
          }  // list operator-action
        }  // list alarm
      }  // container alarm-list
    }  // container alarms

    rpc compress {
      description
        "This action requests the server to compress the alarm entry by
      removing the history of this alarm. The latest state
      change will be kept.";
      input {
        leaf alarm-type-id {
          type leafref {
            path "/alarms/alarm-list/alarm/alarm-type-id";
          }
          description
            "Compress alarms with this alarm-type-id.";
        }

        leaf alarm-type-qualifier {
          type leafref {
            path "/alarms/alarm-list/alarm[alarm-type-id=current()/../alarm-type-id]/alarm-type-qualifier";
          }
          description
            "Compress the alarm with this alarm-type-qualifier.";
        }

        leaf resource {
          type leafref {
            path "/alarms/alarm-list/alarm[alarm-type-id=current()/../alarm-type-id][alarm-type-qualifier=current()/../alarm-type-qualifier]/resource";
          }
          description
            "Compress the alarm with this resource.";
        }
      }

      output {
        leaf result {
          type string;
          description
            "Information on the compress operation.";
        }

        leaf compressed-elements {
          type uint16;
          description
            "Number of removed entries";
        }
      }
    }  // rpc compress

    rpc compress-alarms {
      description
        "This operation requests the server to compress the alarm
entries by removing the history of each individual alarm.  The
latest state change will be kept.  Note that no alarm entries
such are removed only the history for each alarm.";
      output {
        leaf result {
          type string;
          description
            "Overall information on the compress rpc";
        }

        leaf compressed-elements {
          type uint16;
          description
            "Total number of compressed entries";
        }
      }
    }  // rpc compress-alarms

    grouping filter-input {
      description
        "Grouping to specify a filter construct on alarm information.";
      leaf alarm-status {
        type enumeration {
          enum "any" {
            value 0;
            description
              "Ignore alarm clearance status";
          }
          enum "cleared" {
            value 1;
            description
              "Filter cleared alarms";
          }
          enum "not-cleared" {
            value 2;
            description
              "Filter not cleared alarms";
          }
        }
        mandatory true;
        description
          "The clearance status of the alarm.";
      }

      container older-than {
        presence "Age specification";
        description
          "Matches the 'last-status-change' leaf in the alarm.";
        choice age-spec {
          description
            "Filter using date and time age.";
          leaf seconds {
            type uint16;
            description "Seconds part";
          }
          leaf minutes {
            type uint16;
            description "Minute part";
          }
          leaf hours {
            type uint16;
            description "Hours part.";
          }
          leaf days {
            type uint16;
            description "Day part";
          }
          leaf weeks {
            type uint16;
            description "Week part";
          }
        }  // choice age-spec
      }  // container older-than

      container severity {
        presence "Severity filter";
        description
          "Filter based on severity.";
        choice sev-spec {
          description
            "Filter based on severity level.";
          leaf below {
            type severity;
            description
              "Severity less than this leaf.";
          }
          leaf is {
            type severity;
            description
              "Severity level equal this leaf.";
          }
          leaf above {
            type severity;
            description
              "Severity level higher than this leaf.";
          }
        }  // choice sev-spec
      }  // container severity

      container operator-state-filter {
        if-feature operator-actions;
        presence "Operator state filter";
        description
          "Filter based on operator state.";
        leaf state {
          type operator-state;
          description
            "Filter on operator state.";
        }

        leaf user {
          type string;
          description
            "Filter based on which operator.";
        }
      }  // container operator-state-filter
    }  // grouping filter-input

    rpc set-operator-state {
      if-feature operator-actions;
      description
        "This is a means for the operator to indicate
the level of human intervention on an alarm.";
      input {
        leaf resource {
          type leafref {
            path "/alarms/alarm-list/alarm[alarm-type-id=current()/../alarm-type-id][alarm-type-qualifier=current()/../alarm-type-qualifier]/resource";
          }
          description
            "Set operator state for alarm with this resource.";
        }

        leaf alarm-type-id {
          type leafref {
            path "/alarms/alarm-list/alarm/alarm-type-id";
          }
          description
            "Set operator state for alarm with this alarm type
identifier.";
        }

        leaf alarm-type-qualifier {
          type leafref {
            path "/alarms/alarm-list/alarm[alarm-type-id=current()/../alarm-type-id]/alarm-type-qualifier";
          }
          description
            "Set operator state for alarm with this alarm qualifier.";
        }

        leaf state {
          type operator-state;
          mandatory true;
          description
            "Set this operator state";
        }

        leaf text {
          type string;
          description
            "Additional optional textual information.";
        }
      }
    }  // rpc set-operator-state

    rpc purge-alarms {
      description
        "This operation requests the server to delete entries from the
alarm list according to the supplied criteria.  Typically it
can be used to delete alarms that are in closed operator state
and older than a specified time.  The number of purged alarms
is returned as an output parameter";
      input {
        uses filter-input;
      }

      output {
        leaf result {
          type string;
          description
            "Overall result for the purge rpc";
        }

        leaf purged-alarms {
          type uint16;
          description
            "Number of purged alarms.";
        }
      }
    }  // rpc purge-alarms

    notification alarm-notification {
      description
        "This notification is used to report a state change for an
alarm.  The same notification is used for sending a newly
raised alarm, a cleared alarm or changing the text and/or
severity of an existing alarm.";
      uses common-alarm-parameters;

      uses alarm-status-change-parameters;
    }  // notification alarm-notification

    notification operator-action {
      if-feature operator-actions;
      description
        "This notification is used to report that an operator
acted upon an alarm";
      leaf resource {
        type resource;
        mandatory true;
        description "The alarming resource.";
      }

      leaf alarm-type-id {
        type alarm-type-id;
        mandatory true;
        description
          "This leaf and the leaf 'alarm-type-qualifier' together
provides a unique identification of the alarm type.";
      }

      leaf alarm-type-qualifier {
        type alarm-type-qualifier;
        description
          "This leaf is used when the 'alarm-type-id' leaf cannot
uniquely identify the alarm type.  Normally, this is not
the case, and this leaf is the empty string.";
      }

      uses operator-parameters;
    }  // notification operator-action
  }  // module ietf-alarms