Working with NETCONF Notification Streams
=========================================

Notification streams are a mechanism that allows users to recieve data from a
network device when specific events occur. The basic concept is that the user
opens a NETCONF session, subscribes to a notification stream, and waits for
stream events to occur in the open session. When the session is ended, the
stream is no longer active.

Opening a NETCONF Session
-------------------------

To start, you must have an active NETCONF session with the device.
Select the device from the "Devices" dropdown, then click "Open device window".

.. image:: images/device-window-no-session.png
   :alt: Screenshot showing a window indicating that the NETCONF session has
         successfully started.

Next, click "Start session" in order to establish an active NETCONF session.

.. image:: images/device-window-with-session.png
   :alt: Screenshot showing a window indicating that the NETCONF session has
         successfully started.

Cisco devices support `draft-ietf-netconf-netconf-event-notifications <https://tools.ietf.org/html/draft-ietf-netconf-netconf-event-notifications-22>`_ (not an official RFC)
using the ietf-event-notifications model.


With the device window open and a session established, you can then construct
NETCONF subscription messages using the ietf-event-notifications model from a
YANG module set (see: "Defining a YANG Module Set). Once you have set values
identifing the stream you wish to recieve events from, click on "Build RPC"
followed by "Run RPC". The subscription message will be sent through the open
session.

.. image:: images/subscription.png
   :alt: Screenshot showing a window with ietf-event-notification module.


NETCONF RFC 5277 Notification Streams
-------------------------------------

YANG Suite also supports `RFC 5277 <https://tools.ietf.org/html/rfc5277>`_
(NETCONF Event Notifications) for supported devices.
If your device supports notifications, YANG Suite provides ready-made actions
to list the supported notification event streams or subscribe to a specific
event stream.

To start, you must have an active NETCONF session with the device.
Select the device from the "Devices" dropdown, then click "Open device window".
Next, click "Start session" in order to establish an active NETCONF session.

.. image:: images/device-window-with-session.png
   :alt: Screenshot showing a window indicating that the NETCONF session has
         successfully started.

In this window, use the "Actions" menu and select the "get streams" action in
order to automatically send the NETCONF RPC used to query for supported
event streams.

.. image:: images/actions-get-streams.png
   :alt: Screenshot showing the "Actions" menu, with "get streams" selected.

If your device *does not* support notifications, you will see an error response
from the device, as in the below example:

.. image:: images/no-support-notify.png
   :alt: Screenshot showing error reply indicating that the device doesn't
         support notifications

If your device *does* support notifications, you should receive a success reply
containing a list of the supported event streams, as in the below example,
which shows a device reporting that it supports two streams,
"NETCONF" and "snmpevents".

.. image:: images/support-notify.png
   :alt: Screenshot showing success reply listing the event streams supported
         by the device

You can subscribe to any given event stream by selecting "Subscribe" from the
Actions menu. A dialog box will pop up prompting you to enter the name of the
desired stream.

.. image:: images/subscribe-notify.png
   :alt: Screenshot showing dialog prompting for stream name

Enter the name of the stream and click "Subscribe". You should see the
"create-subscription" RPC being sent and acknowledged by the device.

Subscribe to the 'snmpevents' event stream and you can see them being
displayed in the window as they happen:

.. image:: images/notify-events.png
   :alt: Screenshot showing a window with the events from the subscribed stream

Currently the only supported way to stop an event stream subscription is to
close the NETCONF session to the device, either by clicking "End Session"
or by closing the session window altogether.
