Topology and Traffic Engineering Notifications

Crosswork Optimization Engine (COE) provides robust support for network topology change notifications using the YANG Data Modeling Language (RFC 7950). These notifications allow you to track real-time changes—such as creation, update, or deletion—of nodes, links, interfaces, and LSPs in your network.

The supported notifications are based on the models and APIs described in:

Layer 3 & Layer 2 Topology Details
Segment Routing Policy Details
Segment Routing Point to Multi-point (Tree-SID) Policy Details
RSVP-TE LSP Details

All these models are defined using YANG, and the API documentation is based on Swagger. Since Swagger does not natively support notification documentation, this page bridges that gap.

API Prefixes Organization

The notification APIs are organized under two main prefixes based on their functionality:

Optimization APIs (`/crosswork/nbi/optimization/v3/restconf`)

LCM Recommendation Event notifications
SR Policy Paths notifications
RSVP LSP notifications (tunnel operations)
SR Point to Multi-Point (Tree-SID) events

Topology APIs (`/crosswork/nbi/topology/v3/restconf`)

SR Policy Change Event notifications
L2 and L3 Topology Event notifications
L3 Termination Point (Interface) Event notifications
L3 Link Event notifications
Node Event notifications
Performance Metrics notifications

Subscribing to Notifications

To receive notifications, you must create a notification stream by sending a POST request to the sal-remote:create-notification-stream RPC. Specify the notifications you want to subscribe to in the request body. The response will include a stream identifier, which you can use to listen for events.

Basic Workflow

Create a notification stream by specifying which notifications you want to subscribe to
Get the stream identifier from the response
Listen for notifications using the stream identifier
Optionally list all streams to manage your subscriptions

Example: Topology API Notification (L3 Node Event)

Step 1: Create a Notification Stream

curl -k -H "Authorization: Bearer $JWT" -H "Accept: application/json" -H "Content-Type: application/yang-data+json" \
  -X POST https://<coe_ip>:30603/crosswork/nbi/topology/v3/restconf/operations/sal-remote:create-notification-stream \
  -d '{"input": {"notifications": ["(urn:ietf:params:xml:ns:yang:ietf-l3-unicast-topology-state?revision=2018-02-26)l3-node-event"], "notification-output-type":"JSON"}}'

Step 2: Sample Response

{
    "sal-remote:output": {
        "notification-stream-identifier": "urn:uuid:67f88d64-b9b0-4910-b2bb-1ef55a8b259e"
    }
}

Step 3: Listen for Notifications

curl -k -N -H "Authorization: Bearer $JWT" https://<coe_ip>:30603/crosswork/nbi/topology/v3/restconf/streams/json/urn:uuid:67f88d64-b9b0-4910-b2bb-1ef55a8b259e

Example: Optimization API Notification (LCM Recommendation Event)

Create a Notification Stream

curl -k -H "Authorization: Bearer $JWT" -H "Accept: application/json" -H "Content-Type: application/yang-data+json" \
  -X POST https://<coe_ip>:30603/crosswork/nbi/optimization/v3/restconf/operations/sal-remote:create-notification-stream \
  -d '{"input": {"notifications": ["(urn:com:cisco:crosswork:optimization-engine:lcm-recommendation:operations?revision=2021-05-06)lcm-recommendation-event"], "notification-output-type":"JSON"}}'

Managing Notification Streams

List All Notification Streams:

curl -k -H "Authorization: Bearer $JWT" https://<coe_ip>:30603/crosswork/nbi/topology/v3/restconf/data/ietf-restconf-monitoring:restconf-state/streams

Sample Output:

{
    "ietf-restconf-monitoring:streams": {
        "stream": [
            {
                "name": "urn:uuid:49d2a961-0d18-458f-bd89-b15f5fa633be",
                "access": [
                    {
                        "encoding": "json",
                        "location": "http://localhost:8181/rests/streams/json/urn:uuid:49d2a961-0d18-458f-bd89-b15f5fa633be"
                    },
                    {
                        "encoding": "xml",
                        "location": "http://localhost:8181/rests/streams/xml/urn:uuid:49d2a961-0d18-458f-bd89-b15f5fa633be"
                    }
                ],
                "description": "YANG notifications matching any of { optima-restconf-test:new-numbers }"
            }
        ]
    }
}

Supported YANG Notification Definitions

The following are the YANG definitions for notifications supported by COE. For full model details, refer to the linked API documentation above.

LCM Recommendation Event

module cisco-crosswork-optimization-engine-lcm-recommendation-operations {
  namespace "urn:com:cisco:crosswork:optimization-engine:lcm-recommendation:operations";
  revision "2021-05-06";
  ...
  notification lcm-recommendation-event {
    uses coe-lcm-recommendation-common:lcm-rec-notification;
  }
}

SR Policy Paths Notification

module cisco-crosswork-optimization-engine-operations {
  namespace "urn:com:cisco:crosswork:optimization-engine:operations";
  revision "2019-08-30";
  ...
  notification interface-sr-policy-paths-notification {
    uses oe-common:interface-sr-policy-path-map;
  }
}

RSVP LSP Notifications

module cisco-crosswork-rsvp-te-tunnel {
    namespace "http://cisco.com/ns/yang/cisco-crosswork-rsvp-te-tunnel";
    revision "2022-11-02";
    ...
    notification tunnel-oper-state-change-event {
        description
          "Notification for change in oper state of a RSVP TE Tunnel";

        leaf rsvp-te-tunnel-headend-ref {
            type leafref {
                path "/rsvp-te-tunnels/rsvp-te-tunnel/headend";
            }
        }
        leaf rsvp-te-tunnel-endpoint-ref {
            type leafref {
                path "/rsvp-te-tunnels/rsvp-te-tunnel/endpoint";
            }
        }
        leaf rsvp-te-tunnel-color-ref {
            type leafref {
                path "/rsvp-te-tunnels/rsvp-te-tunnel/tunnel-id";
            }
        }
        leaf new-oper-state {
            type tunnel-types:rsvp-oper-state;
            description
              "New operational state of the RSVP TE Tunnel";
        }
        leaf admin-state {
            type tunnel-types:rsvp-admin-state;
            description
              "Administrative state of the RSVP TE Tunnel";
        }
    }

    notification tunnel-change-event {
        description
          "Notification for any change in a RSVP TE tunnel. Contains 
           the latest values of all properties and states";

        leaf change-type {
            description
              "Indicates whether the RSVP TE Tunnel was Created, Updated or Deleted. 
               In case of Deletion, only the Tunnel headend, endpoint and 
               tunnel-id will be reported";

            type enumeration {
                enum RSVP-TUNNEL-CREATE;
                enum RSVP-TUNNEL-UPDATE;
                enum RSVP-TUNNEL-DELETE;
            }
        }
        container rsvp-te-tunnel {
            description
              "Complete information of the RSVP TE Tunnel that got changed";

            uses tunnel-info;
        }
    }
}

SR Point to Multi-Point (Tree-SID) Event

module cisco-crosswork-segment-routing-p2mp-policy {
  namespace "http://cisco.com/ns/yang/cisco-crosswork-segment-routing-p2mp-policy";
  revision "2022-07-07";
  ...
  notification p2mp-policy-change-event {
    description
      "Notification for any change in a P2MP Policy. Contains
       the latest values of all properties and states";

    leaf change-type {
      description
        "Indicates whether the policy was Created, Updated or Deleted.
         In case of Deletion, only the policy name is guaranteed to be reported
         in this notification.";

      type enumeration {
        enum POLICY-CREATE;
        enum POLICY-UPDATE;
        enum POLICY-DELETE;
      }
    }
    container p2mp-policy {
      description
        "Complete information of the P2MP Policy for this change event";

      uses p2mp-policy-info;
    }
  }
}

SR Policy Change Event

module cisco-crosswork-segment-routing-policy {
  namespace "http://cisco.com/ns/yang/cisco-crosswork-segment-routing-policy";
  revision "2021-06-15";
  ...
  notification sr-policy-oper-state-change-event {
    description 
      "Notification for change in oper state of a SR Policy";
    
    leaf policy-headend-ref {
      type leafref {
        path "/sr-policies/policy/headend";
      }
    }
    leaf policy-endpoint-ref {
      type leafref {
        path "/sr-policies/policy/endpoint";
      }
    }
    leaf policy-color-ref {
      type leafref {
        path "/sr-policies/policy/color";
      }
    }
    leaf new-oper-state {
      type sr-types:policy-oper-state;
      description 
        "New operational state of the policy";
    }
    leaf admin-state {
      type sr-types:policy-admin-state;
      description 
        "Administrative state of the policy";
    }
  }
  
  notification sr-policy-change-event {
    description
      "Notification for any change in a SR Policy. Contains 
       the latest values of all properties and states";
    
    leaf change-type {
      description
        "Indicates whether the policy was Created, Updated or Deleted. 
         In case of Deletion, only the policy headend, endpoint and 
         color will be reported";
      
      type enumeration {
        enum POLICY-CREATE;
        enum POLICY-UPDATE;
        enum POLICY-DELETE;
      }
    }
    container policy {
      description
        "Complete information of the SR Policy that got changed";

      uses sr-policy-info;
    }
  }
}

L2 and L3 Topology Events

module ietf-l2-topology-state {
  namespace "urn:ietf:params:xml:ns:yang:ietf-l2-topology-state";
  revision "2020-11-15";
  ...
  notification l2-node-event {
    description
      "Notification event for L2 node.";
    leaf event-type {
      type l2t:l2-network-event-type;
      description
        "Event type.";
    }
    uses nw-s:node-ref;
    uses l2t:l2-network-type;
    uses l2t:l2-node-attributes;
  }

  notification l2-link-event {
    description
      "Notification event for an L2 link.";
    leaf event-type {
      type l2t:l2-network-event-type;
      description
        "Event type.";
    }
    uses nt-s:link-ref;
    uses l2t:l2-network-type;
    uses l2t:l2-link-attributes;
  }

  notification l2-termination-point-event {
    description
      "Notification event for L2 termination point.";
    leaf event-type {
      type l2t:l2-network-event-type;
      description
        "Event type.";
    }
    uses nt-s:tp-ref;
    uses l2t:l2-network-type;
    uses l2t:l2-termination-point-attributes;
  }
}

L3 Termination Point (Interface) Event and L3 Link Event

module ietf-l3-unicast-topology-state {
  namespace
    "urn:ietf:params:xml:ns:yang:ietf-l3-unicast-topology-state";
  revision "2018-02-26";
  ...
  notification l3-node-event {
    description
      "Notification event for L3 node";
    leaf l3-event-type {
      type l3t:l3-event-type;
      description
        "Event type";
    }
    uses nw-s:node-ref;
    uses l3t:l3-unicast-topology-type;
    uses l3t:l3-node-attributes;
  }
  notification l3-link-event {
    description
      "Notification event for L3 link";
    leaf l3-event-type {
      type l3t:l3-event-type;
      description
        "Event type";
    }
    uses nt-s:link-ref;
    uses l3t:l3-unicast-topology-type;
    uses l3t:l3-link-attributes;
  }
  notification l3-prefix-event {
    description
      "Notification event for L3 prefix";
    leaf l3-event-type {
      type l3t:l3-event-type;
      description
        "Event type";
    }
    uses nw-s:node-ref;
    uses l3t:l3-unicast-topology-type;
    container prefix {
      description
        "Contains L3 prefix attributes";
      uses l3t:l3-prefix-attributes;
    }
  }
  notification termination-point-event {
    description
      "Notification event for L3 termination point";
    leaf l3-event-type {
      type l3t:l3-event-type;
      description
        "Event type";
    }
    uses nt-s:tp-ref;
    uses l3t:l3-unicast-topology-type;
    uses l3t:l3-termination-point-attributes;
  }
}

Node Event (this is relevant for both L3 and L2 topology information)

module ietf-l3-unicast-topology-state {
    yang-version 1.1;
    namespace "urn:ietf:params:xml:ns:yang:ietf-l3-unicast-topology-state";
    ...
    notification l3-node-event {
        description
            "Notification event for L3 node";
        leaf l3-event-type {
            type l3t:l3-event-type;
            description
                "Event type";
        }
        uses nw-s:node-ref;
        uses l3t:l3-unicast-topology-type;
        uses l3t:l3-node-attributes;
    }
}

Usage Examples

Before receiving notifications, ensure the relevant notification API is enabled. The following examples assume you have a valid JWT authentication token.

Subscribe to L3 Link Events:

curl -k -H "Authorization: Bearer $JWT" -H "Accept: application/json" -H "Content-Type: application/yang-data+json" \
  -X POST  https://<coe_ip>:30603/crosswork/nbi/topology/v3/restconf/operations/sal-remote:create-notification-stream \
  -d '{"input": {"notifications": ["(urn:ietf:params:xml:ns:yang:ietf-l3-unicast-topology-state?revision=2018-02-26)l3-node-event"], "notification-output-type":"JSON"}}'

curl -k -H "Authorization: Bearer $JWT" -N https://<coe_ip>:30603/crosswork/nbi/topology/v3/restconf/streams/json/$UUID

Sample Notification Output:

{
   "ietf-restconf:notification":{
      "ietf-l3-unicast-topology-state:l3-link-event":{
         "l3-link-attributes":{
            "name":"xrv9k-4 : GigabitEthernet0/0/0/2 : xrv9k-7 : GigabitEthernet0/0/0/2 : IPv4",
            "metric2":"10",
            "metric1":"10",
            "ietf-sr-mpls-topology-state:sr-mpls":{
               "advertise-protection":"dual",
               "sids":[
                  { "sid":24000, "is-backup":false, ... },
                  { "sid":24001, "is-backup":true, ... }
               ],
               "information-source":"isis"
            },
            "cisco-crosswork-l3-te-topology:l3-link-attributes":{
               "administrative-group":0,
               "domain-id":"1000",
               "max-bandwidth-kbps":"1000000"
            },
            "cisco-crosswork-isis-topology:isis-link-attributes":{
               "level":2,
               "net":{ "system-id":"0000.0000.0004" }
            }
         },
         "l3-unicast-topology":{ "cisco-crosswork-isis-topology:isis":{} },
         "link-ref":"xrv9k-4 : GigabitEthernet0/0/0/2 : xrv9k-7 : GigabitEthernet0/0/0/2 : IPv4",
         "l3-event-type":"update",
         "network-ref":"Default-network"
      }
   },
   "event-time":"2023-04-27T21:25:26.602324Z"
}

Subscribe to SR Policy Events:

curl -k -H "Authorization: Bearer $JWT" -H "Accept: application/json" -H "Content-Type: application/yang-data+json" \
  -X POST  https://<coe_ip>:30603/crosswork/nbi/topology/v3/restconf/operations/sal-remote:create-notification-stream \
  -d '{"input": {"notifications": ["(http://cisco.com/ns/yang/cisco-crosswork-segment-routing-policy?revision=2021-06-15)sr-policy-change-event"], "notification-output-type":"JSON"}}'

curl -k -H "Authorization: Bearer $JWT" -N https://<coe_ip>:30603/crosswork/nbi/topology/v3/restconf/streams/json/$UUID