Cisco NSO Service Manager

NETCONF event streams

NSO emits notifications over NETCONF for events that occur within its system — service deployments, alarm changes, device state changes, and more. The NSO adapter can subscribe to these streams, and Platform workflows can be configured to wait for and respond to specific events.

How it works

  1. NSO event streams are defined in ncs.conf on the NSO server.
  2. The NSO adapter is configured with a list of streams to subscribe to (netconfSubscriptions).
  3. Platform workflows use the eventListener task to pause execution until a specific event is received from a subscribed stream.
  4. When the event arrives, the workflow resumes and processes the event payload.

Step 1: Configure NSO event streams

NSO supports the following built-in event streams:

  • ncs-alarms
  • ncs-events
  • device-notifications
  • service-state-changes
  • NETCONF

Every stream that the adapter will subscribe to must be defined in ncs.conf, even if it does not support replay. The following example configures the ncs-alarms stream:

1<notifications>
2  <event-streams>
3    <stream>
4      <n>ncs-alarms</n>
5      <description>NCS alarms according to tailf-ncs-alarms.yang</description>
6      <replay-support>false</replay-support>
7      <builtin-replay-store>
8        <enabled>false</enabled>
9        <dir>./state</dir>
10        <max-size>S10M</max-size>
11        <max-files>50</max-files>
12      </builtin-replay-store>
13    </stream>
14  </event-streams>
15</notifications>

Repeat for each stream you want to enable. Refer to the Cisco NSO documentation for stream-specific configuration options.

Step 2: Configure the adapter to subscribe

In the NSO adapter service config, set netconfSubscriptions to the list of streams the adapter should subscribe to. The values must match the stream names defined in ncs.conf.

The adapter must be restarted after updating this property for the subscription changes to take effect.

1{
2  "id": "NSO",
3  "type": "NSO",
4  "properties": {
5    "netconfSubscriptions": [
6      "ncs-events",
7      "ncs-alarms",
8      "device-notifications",
9      "service-state-changes"
10    ],
11    "http": {
12      "host": "localhost",
13      "port": 8080
14    },
15    "netconf": {
16      "host": "localhost",
17      "port": 2022,
18      "protocol": "ssh"
19    },
20    "credentials": {
21      "user": "admin",
22      "passwd": "admin"
23    },
24    "commitWait": 5000,
25    "commitQueue": false
26  }
27}

Step 3: Configure the eventListener workflow task

In Automation Studio, use the eventListener task to pause a workflow until a specific NSO event is received.

When a workflow job reaches an eventListener task, it enters a running state and waits. Once the specified event arrives, the task completes and the workflow continues.

Task inputs

InputDescription
Event SourceThe adapter publishing the event. For NSO, use the fully qualified adapter location: @itential/adapter-nso. If multiple NSO adapters are configured, specify the correct one by name.
Event TopicThe name of the NETCONF stream to listen on (for example, service-state-changes).
Event Schema FilterA JSON schema used to filter events. The task only proceeds when the incoming event payload matches the schema. Use an empty object {} to accept any event on the specified topic without filtering.

Event Schema Filter example

The following schema filter causes the eventListener task to proceed only when it receives a plan-state-change event for the l3vpn service named IAP with status reached:

Expected event payload:

1{
2  "eventTime": "2019-09-19T18:56:14.227091+01:00",
3  "plan-state-change": {
4    "service": {
5      "_": "/l3vpn:l3vpn-simple-svc[l3vpn:name='IAP']"
6    },
7    "component": "self",
8    "state": {
9      "_": "ncs:init"
10    },
11    "operation": "created",
12    "status": "reached"
13  }
14}

Corresponding Event Schema Filter:

1{
2  "type": "object",
3  "properties": {
4    "eventTime": {
5      "type": "string",
6      "format": "date-time"
7    },
8    "plan-state-change": {
9      "type": "object",
10      "properties": {
11        "service": {
12          "type": "object",
13          "properties": {
14            "_": {
15              "type": "string",
16              "enum": ["/l3vpn:l3vpn-simple-svc[l3vpn:name='IAP']"]
17            }
18          },
19          "required": ["_"],
20          "additionalProperties": false
21        },
22        "component": { "type": "string" },
23        "state": {
24          "type": "object",
25          "properties": {
26            "_": { "type": "string" }
27          },
28          "required": ["_"],
29          "additionalProperties": false
30        },
31        "operation": { "type": "string" },
32        "status": { "type": "string" }
33      },
34      "required": ["service", "component", "state", "operation", "status"],
35      "additionalProperties": false
36    }
37  },
38  "required": ["eventTime", "plan-state-change"],
39  "additionalProperties": false
40}

To listen for any event on a stream without filtering by payload, set the Event Schema Filter to {}.