The set of event notifications delivered in an event stream may be further refined by applying a user-specified filter supplied at subscription creation time ( <create-subscription> ). This is a transient filter associated with the event notification subscription and does not modify the event stream configuration. The filter element is applied against the contents of the <notification> wrapper and not the wrapper itself. See section 5 for examples. Either subtree or XPath filtering can be used.



Filter Mechanics

The Filter parameter specifies a boolean filter that should be applied to the stream. This is the same format as the standard <filter> element in RFC 6241, except that instead of creating a subset of the database for an <rpc-reply> PDU, the filter is used as a boolean test to send or drop each notification delivered from the server.

  • If any nodes are left in the 'test response', the server will send the entire notification.

  • If the result is empty after the filter is applied to the “test response”, then the server will not send the notification at all.

  • It is possible that access control will either cause the a notification to be dropped entirely, or may be pruned and still delivered. The standard is not clear on this topic. The netconfd-pro server will prune any unauthorized payload from an eventType, but if the <eventType> itself is unauthorized, the entire notification will be dropped.


For more notification filtering examples and details reference to RFC 5277.


For subtree filtering, a non-empty node set means that the filter matches. For XPath filtering, the mechanisms defined in should be used to convert the returned value to boolean.


Filtering is explicitly stated when the event notification subscription is created. This is specified via the 'filter' parameter. A Filter only exists as a parameter to the subscription.



Filtering Examples


The following section provides examples to illustrate the various methods of filtering content on an event notification subscription.


Subtree Filtering



XML subtree filtering is not well-suited for creating elaborate filter definitions given that it only supports equality comparisons

and application of the logical OR operators (e.g., in an event subtree, give me all event notifications that have severity=critical, severity=major, or severity=minor). Nevertheless, it may be used for defining simple event notification forwarding filters as shown below.


The following example illustrates how to select fault events which have severities of critical, major, or minor.  The filtering criteria evaluation is as follows:


((fault & severity=critical) | (fault & severity=major) | (fault & severity=minor))


The following example illustrates how the <create-subscription> operation can be sent by using inline XML file with filtering:


yangcli-pro> create-subscription stream=example-stream filter="""
            <filter netconf:type="subtree">
              <event xmlns="http://example.com/event/1.0">
                <eventClass>fault</eventClass>
                <severity>critical</severity>
              </event>
            </filter>
"""
Note that if you are using custom stream the server will send notification only to the subscription with that stream. Your SIL code notification callback will have to queue notification with help of the following API in order to send the notification only to that stream; otherwise they will be sent to default NETCONF stream:

agt_not_queue_notification_stream((const xmlChar *)"example-stea", notif);

The complete <create-subscription> RPC may look as follows:



        <netconf:rpc netconf:message-id="101"
                xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
          <create-subscription
              xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
            <filter netconf:type="subtree">
              <event xmlns="http://example.com/event/1.0">
                <eventClass>fault</eventClass>
                <severity>critical</severity>
              </event>
              <event xmlns="http://example.com/event/1.0">
                <eventClass>fault</eventClass>
                <severity>major</severity>
              </event>
              <event xmlns="http://example.com/event/1.0">
                <eventClass>fault</eventClass>
                <severity>minor</severity>
              </event>
            </filter>
          </create-subscription>
        </netconf:rpc>


The following example illustrates how to select state or config EventClasses or fault events that are related to card Ethernet0. The filtering criteria evaluation is as follows:


   ( state | config | ( fault & ( card=Ethernet0)))



<netconf:rpc netconf:message-id="101"
                xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
      <create-subscription
          xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
        <filter netconf:type="subtree">
          <event xmlns="http://example.com/event/1.0">
            <eventClass>state</eventClass>
          </event>
          <event xmlns="http://example.com/event/1.0">
            <eventClass>config</eventClass>
          </event>
          <event xmlns="http://example.com/event/1.0">
            <eventClass>fault</eventClass>
            <reportingEntity>
              <card>Ethernet0</card>
            </reportingEntity>
          </event>
        </filter>
      </create-subscription>
</netconf:rpc>


XPath Filters



The following XPath example illustrates how to select fault EventClass notifications that have severities of critical, major, or minor.  The filtering criteria evaluation is as follows:

((fault) & ((severity=critical) | (severity=major) | (severity = minor)))



<netconf:rpc netconf:message-id="101"
                xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
        <create-subscription
              xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
          <filter netconf:type="xpath"
                  xmlns:ex="http://example.com/event/1.0"
             select="/ex:event[ex:eventClass='fault' and
                  (ex:severity='minor' or ex:severity='major'
                       or ex:severity='critical')]"/>
        </create-subscription>
      </netconf:rpc>



The following example illustrates how to select state and config EventClasses or fault events of any severity that come from card Ethernet0.  The filtering criteria evaluation is as follows:

( state | config | (fault & card=Ethernet0))



<netconf:rpc message-id="101"
              xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
        <create-subscription
           xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
             <filter netconf:type="xpath"
                     xmlns:ex="http://example.com/event/1.0"
                select="/ex:event[
                   (ex:eventClass='state' or ex:eventClass='config') or
                   ((ex:eventClass='fault' and ex:card='Ethernet0'))]"/>
       </create-subscription>
     </netconf:rpc>