> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/cisco-nso/netconf-events/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# NETCONF event streams

> Subscribe to NSO NETCONF event streams and use the eventListener workflow task to trigger automations from NSO events.

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:

```xml
<notifications>
  <event-streams>
    <stream>
      <n>ncs-alarms</n>
      <description>NCS alarms according to tailf-ncs-alarms.yang</description>
      <replay-support>false</replay-support>
      <builtin-replay-store>
        <enabled>false</enabled>
        <dir>./state</dir>
        <max-size>S10M</max-size>
        <max-files>50</max-files>
      </builtin-replay-store>
    </stream>
  </event-streams>
</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.

```json
{
  "id": "NSO",
  "type": "NSO",
  "properties": {
    "netconfSubscriptions": [
      "ncs-events",
      "ncs-alarms",
      "device-notifications",
      "service-state-changes"
    ],
    "http": {
      "host": "localhost",
      "port": 8080
    },
    "netconf": {
      "host": "localhost",
      "port": 2022,
      "protocol": "ssh"
    },
    "credentials": {
      "user": "admin",
      "passwd": "admin"
    },
    "commitWait": 5000,
    "commitQueue": false
  }
}
```

## 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

| Input               | Description                                                                                                                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Event Source        | The 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 Topic         | The name of the NETCONF stream to listen on (for example, `service-state-changes`).                                                                                                                    |
| Event Schema Filter | A 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:**

```json
{
  "eventTime": "2019-09-19T18:56:14.227091+01:00",
  "plan-state-change": {
    "service": {
      "_": "/l3vpn:l3vpn-simple-svc[l3vpn:name='IAP']"
    },
    "component": "self",
    "state": {
      "_": "ncs:init"
    },
    "operation": "created",
    "status": "reached"
  }
}
```

**Corresponding Event Schema Filter:**

```json
{
  "type": "object",
  "properties": {
    "eventTime": {
      "type": "string",
      "format": "date-time"
    },
    "plan-state-change": {
      "type": "object",
      "properties": {
        "service": {
          "type": "object",
          "properties": {
            "_": {
              "type": "string",
              "enum": ["/l3vpn:l3vpn-simple-svc[l3vpn:name='IAP']"]
            }
          },
          "required": ["_"],
          "additionalProperties": false
        },
        "component": { "type": "string" },
        "state": {
          "type": "object",
          "properties": {
            "_": { "type": "string" }
          },
          "required": ["_"],
          "additionalProperties": false
        },
        "operation": { "type": "string" },
        "status": { "type": "string" }
      },
      "required": ["service", "component", "state", "operation", "status"],
      "additionalProperties": false
    }
  },
  "required": ["eventTime", "plan-state-change"],
  "additionalProperties": false
}
```

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

## Related reading

* [Configure the NSO adapter](./configure-adapter)
* [RESTCONF API](./restconf-api)

> Subscribe to NSO NETCONF event streams and use the eventListener workflow task to trigger automations from NSO events.