Cisco Crosswork Hierarchical Controller 8.0 NBI and SHQL Reference Guide

 

Introducing Crosswork Hierarchical Controller APIs

Cisco Crosswork Hierarchical Controller offers an extensive set of APIs as a northbound interface to service orchestrators, OSSs, and Inventory systems. These APIs are essential tools to automate operational workflows, planning scenarios, and administrative tasks. These APIs can be used to retrieve information, provision services and resources, build the network and register for notifications.

Crosswork Hierarchical Controller makes use of multiple technologies for these APIs:

●       RESTCONF – based on YANG models defined for NETCONF

●       REST with JSON in body

●       REST with SHQL in body

API Architecture and Technologies

RESTCONF/YANG Protocol Introduction

The RESTCONF protocol is an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG 1.0 [RFC 6020] or YANG 1.1 [RFC 7950] using the data store concepts defined in the Network Configuration Protocol (NETCONF) [RFC 6241] and further extended in NMDA [RFC 8342].

The main reasons for selecting RESTCONF include:

●       The capability of mapping HTTP CRUD operations to provide a model-driven API.

●       The ability to use a ubiquitous REST architecture used by many Web applications.

●       The ability to use and mix various standard data models defined in the YANG modeling language produced by multiple SDOs. This potentially allows an implementor a choice of SDN architectures, namely IETF ACTN, ONF TAPI, and MEF TAPI.

Crosswork Hierarchical Controller’s RESTCONF implementation consists of the following resources:

●       +restconf}/data (Data API): Create/Retrieve/Update/Delete (CRUD) based API for the entire configuration data tree defined in the YANG data models.

●       +restconf}/operations (Operations API): RPC-based API entry to trigger RPC defined in YANG.

●       +restconf}/data/ietf-restconf-monitoring:restconf-state/streams (Notifications API): RESTCONF API to discover possible Notification streams as defined in RESTCONF protocol. See Device Management for more information.

●       +restconf}/yang-library-version: This mandatory leaf identifies the revision date of the "ietf-yang-library" YANG module that is implemented by this server.

As per RFC 8040, the RESTCONF implementation supports JSON encoding for YANG data [RFC 7951]. The server accepts “application/yang-data+json”.

Query Filtering

According to the RESTCONF specification, each operation allows zero or more query parameters to be   present in the request URI. Specifically, query operations’ parameters are described in Section 4.8 of [RFC 8040]. The following table describes the supported query parameters.

Table 1.           Supported Query Parameters

Transport Security

Data Integrity

Crosswork Hierarchical Controller serves all NBI-accessed data over TLS [RFC 5246] – a transport-layer providing data integrity and confidentiality. Any client accessing Crosswork Hierarchical Controller MUST support TLS 1.2 and above.

Server Authentication

Crosswork Hierarchical Controller NBI presents an X.509v3 certificate upon establishing a TLS connection with a client.

A client MUST support certificate validation as per RESTCONF [RFC 8040 Section 2]. The RESTCONF client MUST either (1) use X.509 certificate path validation [RFC5280] to verify the integrity of the RESTCONF server's TLS certificate or (2) match the server's TLS certificate with a certificate obtained by a trusted mechanism (e.g., a pinned certificate).  If the X.509 certificate path validation fails and the presented X.509 certificate does not match a certificate obtained by a trusted mechanism, the connection MUST be terminated, as described in Section 7.2.1 of [RFC5246].

NOTE: For the purpose of testing, a client may disable certificate validation to check interface functionality.

Client Authentication

Crosswork Hierarchical Controller client authentication is based on HTTP Basic Authentication [RFC 7617]. A client must present a username and password over the established TLS connection. More specifically, a client must use an Authorization header using a Basic authentication scheme. For further information, see the HTTP Authentication Scheme Registry [RFC 7235].

API Endpoints

Crosswork Hierarchical Controller supports APIs for receiving notifications, information, and provisioning services.

●       Device manager: Various APIs that allow you to manage adapters, devices and credentials

●       Get inventory: Get optical devices and routers, their cards, ports, and their attributes.

●       Get performance counters: Get L2 performance (throughput) counters per specific port or link.

●       Cross links: Various APIs to administer cross links.

●       Shared risk: Various APIs that allow you to administer shared risk policies and rules.

●       Root Cause Analysis: Various APIs for RCA.

●       Generic queries: Use SHQL commands to query any data from the Crosswork Hierarchical Controller model.

Object IDs

Any reference to specific objects in the APIs uses object IDs. IDs can be used for a network, site, node, TP (termination point), LSP, service, link, network access, or VLAN.

The implementation by Crosswork Hierarchical Controller for these IDs is the GUID. The GUID is a unique identifier of any object in the model and it can be retrieved as the object ID using the relevant GET API. Once retrieved, it can be used as the object reference further on.

Device Management

Crosswork Hierarchical Controller provides APIs to administer device management. 

You can access the Device Manager API using Swagger:

●       https://<host>/api/v2/apps/device-manager-srv/rest/doc

The APIs include:

●       Get all adapters

●       Get adapter configuration schema

●       Get adapter device schema

●       Get all devices

●       Add device to Crosswork Hierarchical Controller

●       Assign device to adapter

●       Update device's adapter configuration

●       Unassign device from adapter

●       Update device name

●       Assign device to Site

●       Get device status

●       Get a device

●       Remove device from Crosswork Hierarchical Controller

●       Get credentials keys' names and types

●       Add new credentials

●       Update credentials

●       Delete credentials

●       Get the parameters schema for the specified credentials type

Get Adapters

Use this API to get the list of all the adapters. The guid in the response is the adapterGuid used in several of the other device manager methods.

Request Method

GET

Request URL

https://example-host/api/v2/apps/device-manager-srv/rest/adapter

Request Parameters

None

Response Example

[

  {

    "guid": "cisco_ios_xr",

    "enabled": true,

    "config": {

      "polling": 300,

      "concurrency": 1,

      "ssh_config": {

        "enabled": false,

        "connect_timeout": 10,

        "command_timeout": 10

      },

      "file_bringer": {

        "enabled": false,

        "location": "",

        "file_type": "XX"

      },

      "collection_parameters": {

        "enable_igp_isis": true,

        "enable_stats": true,

        "enable_vrf": true,

        "enable_lldp": true,

        "enable_mpls": true,

        "enable_snmp": true,

        "igp_isis_priority": 1,

        "igp_seed_routers": true

      }

    }

  },

  {

    "guid": "juniper_os_1",

    "enabled": true,

    "config": {

      "polling": 300,

      "concurrency": 1,

      "ssh_config": {

        "enabled": false,

        "connect_timeout": 10,

        "command_timeout": 10

      },

      "file_bringer": {

        "enabled": false,

        "location": "",

        "file_type": "XX"

      },

      "collection_parameters": {

        "enable_igp_isis": true,

        "enable_igp_ospf": true,

        "enable_stats": true,

        "enable_vrf": true,

        "enable_lldp": true,

        "enable_mpls": true,

        "enable_snmp": true,

        "igp_isis_priority": 1,

        "igp_seed_routers": true

      }

    }

  }

]

Get Adapter Configuration Schema

Use this API to retrieve the adapter's configuration schema.

Request Method

GET

Request URL

https://example-host/api/v2/apps/device-manager-srv/rest/ adapter/{adapterGuid}/adapter-schema

Request Parameters

Response Example

{

  "$schema": "http://json-schema.org/draft-04/schema#",

  "type": "object",

  "properties": {

    "polling": {

      "type": "integer",

      "minimum": 0,

      "default": 300,

      "title": "Polling Cycle [sec]",

      "description": "Poll every X seconds"

    },

    "concurrency": {

      "type": "integer",

      "default": 1,

      "title": "Number of concurrent routers collected"

    },

    "ssh_config": {

      "type": "object",

      "title": "SSH Configuration Parameters",

      "properties": {

        "enabled": {

          "type": "boolean",

          "default": false,

          "title": "Enable Tunnel"

        },

        "host": {

          "type": "string",

          "title": "Tunnel Host"

        },

        "port": {

          "type": "integer",

          "title": "Tunnel Port"

        },

        "tunnel_credentials_key": {

          "type": "string",

          "title": "Tunnel Credentials Key",

          "credentials-types": [

            "SSH_USER_PASSWORD"

          ]

        },

        "connect_timeout": {

          "type": "integer",

          "default": 10,

          "title": "Router Connect timeout"

        },

        "command_timeout": {

          "type": "integer",

          "default": 10,

          "title": "Router Command timeout"

        }

      },

      "additionalProperties": false

    },

    "file_bringer": {

      "type": "object",

      "title": "File Bringer Parameters",

      "properties": {

        "enabled": {

          "type": "boolean",

          "default": false,

          "title": "Enable File Bringer"

        },

        "location": {

          "type": "string",

          "title": "File Server Location",

          "description": "\"[sftp|file]://<server>:<port>/<absolute path>\"",

          "default": ""

        },

        "file_type": {

          "title": "File Type",

          "enum": [

            "XX",

            "XX"

          ],

          "default": "XX"

        },

        "authentication": {

          "type": "string",

          "credentials-types": [

            "SFTP"

          ]

        }

      },

      "additionalProperties": false

    },

    "collection_parameters": {

      "type": "object",

      "title": "Collection Parameters",

      "properties": {

        "enable_igp_isis": {

          "type": "boolean",

          "default": false,

          "title": "Enable IGP IS-IS Collection"

        },

        "enable_stats": {

          "type": "boolean",

          "default": false,

          "title": "Enable Stats Collection"

        },

        "enable_vrf": {

          "type": "boolean",

          "default": false,

          "title": "Enable VRF Collection"

        },

        "enable_lldp": {

          "type": "boolean",

          "default": false,

          "title": "Enable LLDP Collection"

        },

        "enable_mpls": {

          "type": "boolean",

          "default": false,

          "title": "Enable MPLS Tunnels Collection"

        },

        "enable_snmp": {

          "type": "boolean",

          "default": false,

          "title": "Enable SNMP Collection"

        },

        "igp_isis_priority": {

          "type": "integer",

          "default": 1,

          "title": "IGP IS-IS Priority"

        },

        "igp_seed_routers": {

          "type": "boolean",

          "default": true,

          "title": "Collect only IGP IS-IS seed routers"

        }

      },

      "additionalProperties": false

    }

  },

  "additionalProperties": false,

  "required": [

    "polling"

  ]

}

Get Adapter Device Schema

Use this API to retrieve the device configuration schema of a specific adapter.

Request Method

GET

Request URL

https://example-host/api/v2/apps/device-manager-srv/rest/adapter/{adpaterGuid}/device-schema

Request Parameters

Response Example

{

  "type": "object",

  "properties": {

    "host": {

      "type": "string"

    },

    "port": {

      "type": "integer",

      "default": 22

    },

    "direct_connect": {

      "type": "boolean",

      "default": false,

      "title": "Direct Connect (avoid tunnel if configured)"

    },

    "authentication": {

      "type": "string",

      "credentials-types": [

        "SSH_USER_PASSWORD"

      ]

    },

    "enabled": {

      "type": "boolean",

      "default": false

    }

  },

  "additionalProperties": false,

  "required": [

    "enabled",

    "host",

    "port"

  ]

}

Get All Devices

Use this API to get all devices for a specific adapter. The device_manager_guid returned in the response is used as the deviceGuid in the relevant device manager APIs.

Request Method

GET

Request URL

https://example-host/api/v2/apps/device-manager-srv/rest/device?adapter={adpaterGuid}

Request Parameters

Response Example

[

  {

    "device_manager_guid": "0a9af2d2-324a-45dd-895e-9e6edb2f9d39",

    "inventory_type": "ROUTER",

    "device_model_guid": "IN/cisco_ios_xr/ROUTER-xrv-p1",

    "name": "cisco_1",

    "adapters": {

      "cisco_ios_xr": {

        "adapter_guid": "cisco_ios_xr",

        "config": {

          "port": 22,

          "direct_connect": true,

          "enabled": true,

          "host": "10.1.0.58",

          "authentication": "Cisco"

        },

        "enabled": false

      }

    },

    "identifiers": {

      "host_name": "10.1.0.58",

      "tid": null,

      "serial": null,

      "loopback_mac": null,

      "loopback_ip": null,

      "extra": {}

    },

    "site": null,

    "pending_delete": false,

    "enabled": false

  },

  {

    "device_manager_guid": "9988749383",

    "inventory_type": "ROUTER",

    "device_model_guid": "IN/cisco_ios_xr/ROUTER-xrv-p2",

    "name": "cisco_2",

    "adapters": {

      "cisco_ios_xr": {

        "adapter_guid": "cisco_ios_xr",

        "config": {

          "port": 22,

          "direct_connect": true,

          "enabled": true,

          "host": "10.1.0.71",

          "authentication": "Cisco"

        },

        "enabled": false

      }

    },

    "identifiers": {

      "host_name": "10.1.0.71",

      "tid": null,

      "serial": null,

      "loopback_mac": null,

      "loopback_ip": null,

      "extra": {}

    },

    "site": null,

    "pending_delete": false,

    "enabled": false

  }

]

Add Device to Crosswork Hierarchical Controller

Use this API to add a device to Crosswork Hierarchical Controller.

Request Method

POST

Request URL

https://example-host/api/v2/apps/device-manager-srv/rest/device

Request Parameters

None

Request Body

Request Body Example

{

  "name": "router-a",

  "site": null

}

Response Example

{

  "device_manager_guid": "a2087abe-5753-4387-b372-f8cfb571bb1e"

}

Assign Device to Adapter

Use this API to assign a device to an adapter.

Request Method

POST

Request URL

https://example-host/api/v2/apps/device-manager-srv/rest/device/{deviceGuid}/adapters/{adapterGuid}

Request Parameters

Request Body

Request Body Example

{

    "host": "1.1.1.1",

    "port": 22,

    "enabled": false

}

Response Example

201 Successful

Update Device Adapter Configuration

Use this API to update the device adapter configuration.

Request Method

PUT

Request URL

https://example-host/api/v2/apps/device-manager-srv/rest/device/{deviceGuid}/adapters/{adapterGuid}

Request Parameters

Request Body

Request Body Example

{

    "host": "1.1.1.1",

    "port": 22,

    "enabled": true

}

Response Example

200 Successful

Unassign Device from Adapter

Use this API to unassign a device from an adapter. The device is not deleted from the network.

Request Method

DELETE

Request URL

https://example-host/api/v2/apps/device-manager-srv/rest/device/{deviceGuid}/adapters/{adapterGuid}

Request Parameters

Response Example

200 Successful

Update Device Name

Use this API to update the device name.

Request Method

PUT

Request URL

https://example-host/api/v2/apps/device-manager-srv/rest/device/{deviceGuid}/name/{name}

Request Parameters

Response Example

200 Successful

Assign Device to Site

Use this API to assign a device to site.

Request Method

PUT

Request URL

https://example-host/api/v2/apps/device-manager-srv/rest/device/{deviceGuid}/site

Request Parameters

Request Body

Request Body Example

{

  "guid": "ST/e7df76d7a9cb"

}

Response Example

200 Successful operation.

Get Device Status

Use this API to get device status.

Request Method

GET

Request URL

https://example-host/api/v2/apps/device-manager-srv/rest/device/{deviceGuid}/status

Request Parameters

Response Example

{

  "adapte-name": {

    "last-successfull-discovery": "2020-05-04T17:50:15.530Z"

  }

}

Get a Device

Use this API to get a device.

Request Method

GET

Request URL

https://example-host/api/v2/apps/device-manager-srv/rest/ device/{deviceGuid}

Request Parameters

Response Example

{

  "device_manager_guid": "83ce57e9-a82b-488a-994b-f8c4191f0158",

  "inventory_type": null,

  "device_model_guid": null,

  "name": "router-a",

  "adapters": {

    "cisco_ios_xr": {

      "adapter_guid": "cisco_ios_xr",

      "config": {

        "host": "1.1.1.2",

        "port": 22,

        "enabled": false

      },

      "enabled": false

    }

  },

  "identifiers": {

    "host_name": null,

    "tid": null,

    "serial": null,

    "loopback_mac": null,

    "loopback_ip": null,

    "extra": {}

  },

  "site": null,

  "pending_delete": false,

  "enabled": false

}

Remove Device from Crosswork Hierarchical Controller

Use this API to remove the device from Crosswork Hierarchical Controller.

Request Method

DELETE

Request URL

https://example-host/api/v2/apps/device-manager-srv/rest/device/{deviceGuid}?force=true

Request Parameters

Response Example

200 OK!

Get Credentials

Use this API to get all configured credentials keys' names and types.

Request Method

GET

Request URL

https://example-host/api/v2/apps/device-manager-srv/rest/credentials?type={type}

Request Parameters

Response Example

[

  {

    "name": "A",

    "type": "SSH_USER_PASSWORD"

  },

  {

    "name": "Cisco",

    "type": "SSH_USER_PASSWORD"

  },

  {

    "name": "junos",

    "type": "SSH_USER_PASSWORD"

  }

]

Add New Credentials

Use this API to add new credentials.

Request Method

POST

Request URL

https://example-host/api/v2/apps/device-manager-srv/rest/credentials/{name}

Request Parameters

Request Body

Request Body Example

{

  "type": "SSH_USER_PASSWORD",

  "config": {}

}

Response Example

201 Successful Operation

Update Credentials

Use this API to update credentials.

Request Method

PUT

Request URL

https://example-host/api/v2/apps/device-manager-srv/rest/credentials/{name}

Request Parameters

Request Body

Request Body Example

{

  "type": "SSH_USER_PASSWORD",

  "config": {}

}

Response Example

200 Successful Operation

Delete Credentials

Use this API to delete credentials.

Request Method

DELETE

Request URL

https://example-host/api/v2/apps/device-manager-srv/rest/ credentials/{name}

Request Parameters

Response Example

200 Successful

Get the Parameters Schema for the Specified Credentials Type

Use this API to get the parameters schema for the specified credentials type.

Request Method

GET

Request URL

https://example-host/api/v2/apps/device-manager-srv/rest/XXX

Request Parameters

Response Example

{

  "type": "object",

  "properties": {

    "username": {

      "title": "Username",

      "type": "string"

    },

    "password": {

      "title": "Password",

      "type": "string",

      "encrypted": true

    }

  },

  "required": [

    "username",

    "password"

  ]

}

Physical Inventory

The physical inventory API provides information on devices attributes, slots, cards, and ports.

This API supports optical devices only.

Get Physical Inventory

The API accepts two queries:

●       Device ID – get full list of devices or specific device by its ID.

●       Full – get detailed device inventory or only its ID (full=true/false).

Request Method

GET

Request URL

/api/v2/apps/network-inventory-app/rest/devices/

Request Header

Accept: application/yang-data+json

Content-Type: application/yang-data+json

Response Example

{

    "id": "XX-01011",

    "type": "ONE",

    "desc": "XX-01011",

    "vendor_model": "ciena_6500",

    "tid": "TID111",

    "serial_number": "[Shelf-1 [1-XX,2-XX]]",

    "SHELF": [

        {

            "id": "1",

            "type": "SHELF",

            "desc": "6500 14-Slot Converged Optical Shelf Assembly, OCP",

            "vendor_model": "ciena_6500",

            "tid": "XX-01011",

            "aid": "SHELF-1",

            "clei": "WWW",

            "serial_number": "SSS",

            "FAN": [

                {

                    "id": "FAN-1-1",

                    "type": "FAN",

                    "desc": "XX-01011/MNG-EQPT/FAN-1-1 (FAN), ctype=\"Fan Rear Exhaust High Flow Cooling\")",

                    "vendor_model": "ciena_6500",

                    "tid": "XX-01011",

                    "aid": "FAN-1-1",

                    "clei": "WWW",

                    "part_number": "NNN",

                    "serial_number": "MMM"

                }

            ],

            "CARD": [

                {

                    "id": "1-1",

                    "type": "CARD",

                    "desc": "XX-01011/1-1 (OTSC), ctype=\"2x10G OTR 4x XFP\")",

                    "vendor_model": "ciena_6500",

                    "tid": "XX-01011",

                    "aid": "OOO-1-1",

                    "clei": "WWW",

                    "part_number": "MM",

                    "serial_number": "NNN",

                    "PORT": [

                        {

                            "id": "1-1-1",

                            "type": "PORT",

                            "desc": "XX-01011/1-1-1 (P10GSOEL), ctype=\"OC192 SR1/I64.1 10GBASE-LR/LW OTU2 10GFC 1200SMLLL 1310 nm XFP\")",

                            "vendor_model": "ciena_6500",

                            "tid": "XX-01011",

                            "aid": "UU-1-1-1",

                            "clei": "WWW",

                            "pluggable": "PLUGGABLE",

                            "part_number": "NNNA",

                            "serial_number": "MMM"

                        },

                       

                },

            

            "POWER_SUPPLY": [

                {

                    "id": "PWR-1-17-1",

                    "type": "POWER_SUPPLY",

                    "desc": "XX-01011/MNG-EQPT/PWR-1-17-1 (PWR), ctype=\"Power Card 60A breakered\")",

                    "vendor_model": "ciena_6500",

                    "tid": "XX-01011",

                    "aid": "PWR-1-17-1",

                    "clei": "WWWD",

                    "part_number": "NNNA",

                    "serial_number": "MMM"

                },

            ]

        }

    ]

}

Response Parameters

The response contains information on all device inventory modules:

●       Device – all device level attributes

●       Shelf – one or more shelves

●       Fan – fan trays

●       Card – all pluggable, line and aggregation cards, including transceivers

●       Port – all physical ports

●       Power supply – all power modules

Performance Counters

The Crosswork Hierarchical Controller performance API is based on a non-SDO data model authored by Cisco. The SDOs lack a network-level, performance data model allowing NBI access to raw performance counters of managed network objects.

Current performance-counter data models in IETF are address the device level, such as ietf-interfaces, whereas network-level data models focus on derived values, e.g., bandwidth. Cisco will implement a standard data model once available from IETF.

The Crosswork Hierarchical Controller data model exposes raw performance counters collected from ports and IP/MPLS LSPs. It is implemented in the form of a YANG RPC where an NBI client may trigger an operation via the RESTCONF NBI to retrieve packet and/or octet counters to derive rate, average, etc.

URIs

You can retrieve the counters for the latest PM interval or for a specific period. The stats can be retrieved for a specific LSP/port/link, all objects, or for a group of objects (set by POST message).

Get Performance Latest Stats

Gets the performance stats for the latest period for an object or all objects. You can specify a specific PM type with a specific port/LSP or stream ID.

Request Method

GET

Request URL

api/v2/timeseries/stats/latest

Request Header

Accept: application/yang-data+json

Content-Type: application/yang-data+json

Request Parameters

Request Example

GET /api/v2/timeseries/stats/latest?pmType=DELAY_USEC&objGuid=PO/juniper-northstar/LGC-LabMX960-02:ae5.0

GET /api/v2/timeseries/stats/latest?pmType=DELAY_USEC&streamId=3

Request Parameters

Response Example

{

  "objGuid": "LI/lsp/f66fa3288d396e47/f66fa3288d396e47/f1e815107b715b67/f1e815107b715b67/lsp_1619081766048",

  "timeStamp": 1622602613000,

  "deviceType": "ROUTER",

  "timePeriodSec": 0,

  "pmType": "OCTET_OUT",

  "value": 273252081213835,

  "streamId": 6

}

Get Performance Stats for Period

Gets the performance stats for a specific period for an object or all objects. You can specify a specific PM type with a specific port/LSP or stream ID.

Request Method

GET

Request URL

api/v2/timeseries/stats

Request Header

Accept: application/yang-data+json

Content-Type: application/yang-data+json

Request Parameters

Request Example

GET /api/v2/timeseries/stats?startTimeStamp=1643793190000&

endTimeStamp=1643878292000&pmTypeDELAY_USEC&objGuid= PO/r_logical/16f1596a46b13da5/7d82f458ff24bfa3

Request Parameters

Response Example

{

  "objGuid": "PO/r_logical/16f1596a46b13da5/7d82f458ff24bfa3",

  "timeStamp": 1643874592000,

  "deviceType": "ROUTER",

  "timePeriodSec": 859,

  "pmType": "DELAY_USEC",

  "value": 649907,

  "streamId": 5

}

{

  "objGuid": "PO/r_logical/16f1596a46b13da5/7d82f458ff24bfa3",

  "timeStamp": 1643875520000,

  "deviceType": "ROUTER",

  "timePeriodSec": 928,

  "pmType": "DELAY_USEC",

  "value": 724091,

  "streamId": 5

}

{

  "objGuid": "PO/r_logical/16f1596a46b13da5/7d82f458ff24bfa3",

  "timeStamp": 1643876484000,

  "deviceType": "ROUTER",

  "timePeriodSec": 927,

  "pmType": "DELAY_USEC",

  "value": 69079,

  "streamId": 5

}

{

  "objGuid": "PO/r_logical/16f1596a46b13da5/7d82f458ff24bfa3",

  "timeStamp": 1643877388000,

  "deviceType": "ROUTER",

  "timePeriodSec": 904,

  "pmType": "DELAY_USEC",

  "value": 665969,

  "streamId": 5

}

Send Specific Ports Performance Stats

Gets the performance stats for a specific period for specific ports (not one and not ALL the ports).

Request Method

PUT

Request URL

api/v2/timeseries/stats/bulkStatsQuery

Request Header

Accept: application/yang-data+json

Content-Type: application/yang-data+json

Request Parameters

Request Example

POST /api/v2/timeseries/stats/bulkStatsQuery?startTimeStamp=1659402468000&endTimeStamp=1659802468000' -d@ports.json

 

Where request.json is list of the guids:

[

    "PO/r_logical/1d80163d31fa18ee/870a15983eafb41f",

    "PO/r_logical/7b4564a1ccb6e4cb/5a52cb94b8d7dbc4"

]

Response Parameters

Response Example

[

  {

    "objGuid": "PO/r_logical/7b4564a1ccb6e4cb/5a52cb94b8d7dbc4",

    "timeStamp": 1659608730000,

    "deviceType": "ROUTER",

    "timePeriodSec": 900,

    "pmType": "MAX_RTT_USEC",

    "value": 481463,

    "streamId": 4

  },

  {

    "objGuid": "PO/r_logical/7b4564a1ccb6e4cb/5a52cb94b8d7dbc4",

    "timeStamp": 1659608730000,

    "deviceType": "ROUTER",

    "timePeriodSec": 900,

    "pmType": "DELAY_USEC",

    "value": 443345,

    "streamId": 4

  },

  {

    "objGuid": "PO/r_logical/7b4564a1ccb6e4cb/5a52cb94b8d7dbc4",

    "timeStamp": 1659608730000,

    "deviceType": "ROUTER",

    "timePeriodSec": 900,

    "pmType": "MIN_RTT_USEC",

    "value": 441197,

    "streamId": 4

  },

  {

    "objGuid": "PO/r_logical/1d80163d31fa18ee/870a15983eafb41f",

    "timeStamp": 1659608735000,

    "deviceType": "ROUTER",

    "timePeriodSec": 900,

    "pmType": "OCTET_OUT",

    "value": 17939855810587,

    "streamId": 4

  }

Cross Links

Crosswork Hierarchical Controller provides APIs to administer cross links. For more information, see the Cisco Crosswork Hierarchical Controller Administration Guide. 

The APIs include:

●       Get all adjacent cross links

●       Validate all cross links

●       Validate a cross link

●       Get all manual cross links

●       Get all manual cross links

●       Get a cross link

●       Add manual cross link to Crosswork Hierarchical Controller

●       Delete a cross link

Note: If the user does not have permission to execute the API, 403 Forbidden is returned. If the wrong credentials are used, 401 Authorization Required is returned.

Get All Adjacent Cross Links

Use this API to return port adjacencies that were discovered using automatic discovery protocols such as LLDP, elements in this list MAY be adjacencies that were not configured and not part of the manual cross list.

Request Method

GET

Request URL

https://example-host/api/v2/crosslinks/adjacencies

Request Parameters

None

Response Example

The response contains information on all adjacent cross links. For cross link it returns the following:

●       interfaceA – deviceName, interfaceName, type, and guid

●       interfaceB – deviceName, interfaceName, type, and guid

●       technology (ETH or NMC)

●       relatedModelObjectGuid

Validate All Cross Links

Use this API to trigger a validation all cross links. This runs a process to update the model (links and paths) based on the latest state of cross links, router-physical links, eth links, etc. Validating all cross links (and adding a new manual cross link) may update the path of a r-phy link and may even create the r-phy link altogether if it did not exist before. As a result of the new manual cross link, this may find the entire optical circuit from end-to-end.

For an Ethernet link, if there is a conflict between a manually added cross link and a cross link detected from the network, the manually added link is removed from Cisco Crosswork Hierarchical Controller network model. The manual link remains in the manual-links db and is re-added to the network model if the network-discovered link disappears AND the manual link gets a positive validation after there are no more conflicts (this is in contrast to never-conflicted manual links that appear in the network model even without a positive validation).

This API method returns an empty result. Use the Get All Manual Cross Links method to view the updated state.

Request Method

GET

Request URL

https://example-host/api/v2/crosslinks/validate

Request Parameters

None

Response Example

None

Validate a Cross Link

Use this API to trigger a validation of a specific cross link.  This API only updates the relevant validation fields of the validated manual cross link without touching the topological model.

Request Method

GET

Request URL

https://example-host/api/v2/crosslinks/validate/{guid}

Response Parameters

Response Example

The response returns the following for the cross link:

●       guid: The link guid

●       interfaceA – deviceName, interfaceName, type, and guid

●       interfaceB – deviceName, interfaceName, type, and guid

●       technology (ETH or NMC)

●       relatedModelObjectGuid

●       additionTimeEpochMillis

●       description

●       validated: Whether the link has been validated.

●       validationResult: The validation result (VALIDATED_BY_PORT_ADJACENCY, VALIDATED_BY_CORRELATION, NOT_CORRELATED, INCONCLUSIVE, UNKNOWN, or CONFLICT).

●       lastValidationCheck: The timestamp when the link was last validated.

●       lastConflictTime: This timestamp is hidden if there was never a conflict. If this is the same as the lastValidationCheck, then the manual link is currently in conflict. If lastValidationCheck is later than the lastConflictTime, then the manual link was in conflict before but is not in conflict currently. If in addition validated is true, this manual link appears in the network model.

●       conflicts: If a link is or was conflicted, the conflicts list is populated with one or two conflicting pairs, one pair per each of the manual-link ports.

{

  "guid": "23f6e6c340268f068f817f8f9484aa54a2ba92d5d7072efd7940308f8ecc8fa5",

  "interfaceA": {

    "deviceName": "CR2.ATH",

    "interfaceName": "TenGigE0/0/1/13",

    "type": "R_PHYSICAL",

    "guid": "PO/r_physical/8ff611ed7ebcd772/2c4e6530608a213d"

  },

  "interfaceB": {

    "deviceName": "SD2ATH02",

    "interfaceName": "ETH-1-1-8",

    "type": "ETH",

    "guid": "PO/eth/ecf4e9a6bbb76cbc/86cdb5c6379e5c62"

  },

  "technology": "ETH",

  "relatedModelObjectGuid": "LI/eth/8ff611ed7ebcd772/2c4e6530608a213d/ecf4e9a6bbb76cbc/86cdb5c6379e5c62",

  "additionTimeEpochMillis": 1666695054475,

  "description": "cross link description",

  "validated": true,

  "validationResult": "VALIDATED_BY_PORT_ADJACENCY",

  "lastValidationCheck": 1668598747209,

  "conflicts": [

    {

      "a": { "deviceName": "dev-name-of-manual-link-interfaceA", "interfaceName": "iface-name-of-manual-link-interfaceA" },

      "b": { "deviceName": "dev-name-of-different-than-manual-link-interfaceB", "interfaceName": "iface-name-different-than-manual-link-interfaceB" }

    },

    {

       "a": { "deviceName": "dev-name-of-manual-link-interfaceB", "interfaceName": "iface-name-of-manual-link-interfaceB" },

       "b": { "deviceName": "dev-name-of-different-than-manual-link-interfaceA", "interfaceName": "iface-name-different-than-manual-link-interfaceA" }

   }

   ]

}

Get All Manual Cross Links

Use this API to return an array of the manual cross links. The guid returned can be used as a request parameter in the other cross link APIs.

Request Method

GET

Request URL

https://example-host/api/v2/crosslinks/manual

Request Parameters

None

Response Example

The response returns an array of cross links with the following:

●       guid

●       interfaceA – deviceName, interfaceName, type, and guid

●       interfaceB – deviceName, interfaceName, type, and guid

●       technology (ETH or NMC)

●       relatedModelObjectGuid

●       additionTimeEpochMillis

●       description

●       validated

●       validationResult (VALIDATED_BY_PORT_ADJACENCY, VALIDATED_BY_CORRELATION, NOT_CORRELATED, INCONCLUSIVE, UNKNOWN, CONFLICT)

●       lastValidationCheck

●       conflicts

{

  "guid": "23f6e6c340268f068f817f8f9484aa54a2ba92d5d7072efd7940308f8ecc8fa5",

  "interfaceA": {

    "deviceName": "CR2.ATH",

    "interfaceName": "TenGigE0/0/1/13",

    "type": "R_PHYSICAL",

    "guid": "PO/r_physical/8ff611ed7ebcd772/2c4e6530608a213d"

  },

  "interfaceB": {

    "deviceName": "SD2ATH02",

    "interfaceName": "ETH-1-1-8",

    "type": "ETH",

    "guid": "PO/eth/ecf4e9a6bbb76cbc/86cdb5c6379e5c62"

  },

  "technology": "ETH",

  "relatedModelObjectGuid": "LI/eth/8ff611ed7ebcd772/2c4e6530608a213d/ecf4e9a6bbb76cbc/86cdb5c6379e5c62",

  "additionTimeEpochMillis": 1666695054475,

  "description": "cross link description",

  "validated": true,

  "validationResult": "VALIDATED_BY_PORT_ADJACENCY",

  "lastValidationCheck": 1668598747209,

  "conflicts": []

}

Get a Cross Link

Use this API to get a manual cross link.

Request Method

GET

Request URL

https://example-host/api/v2/crosslinks/manual/{guid}

Request Parameters

Response Example

The response returns the following for the cross link:

●       guid

●       interfaceA – deviceName, interfaceName, type, and guid

●       interfaceB – deviceName, interfaceName, type, and guid

●       technology (ETH or NMC)

●       relatedModelObjectGuid

●       additionTimeEpochMillis

●       description

●       validated: Whether the link has been validated.

●       validationResult: The validation result (VALIDATED_BY_PORT_ADJACENCY, VALIDATED_BY_CORRELATION, NOT_CORRELATED, INCONCLUSIVE, UNKNOWN, or CONFLICT).

●       lastValidationCheck: The timestamp when the link was last validated.

●       lastConflictTime: This timestamp is hidden if there was never a conflict. If this is the same as the lastValidationCheck, then the manual link is currently in conflict. If lastValidationCheck is later than the lastConflictTime, then the manual link was in conflict before but is not in conflict currently. If in addition validated is true, this manual link appears in the network model.

●       conflicts: If a link is or was conflicted, the conflicts list is populated with one or two conflicting pairs, one pair per each of the manual-link ports.

{

  "guid": "fa6262a2f1202b4bba1dd699cc78b2cf9cc45c826487de6daad69e3fa0cf0a90",

  "interfaceA": {

    "deviceName": "CR2.BCN",

    "interfaceName": "TenGigE0/0/1/8",

    "type": "R_PHYSICAL",

    "guid": "PO/r_physical/b876eefb0f288974/146956e90f8b5b6d"

  },

  "interfaceB": {

    "deviceName": "OTN1MIL01",

    "interfaceName": "1-2-3",

    "type": "ETH",

    "guid": "PO/eth/5979a210307b1e66/fba4016fb0ebde72"

  },

  "technology": "ETH",

  "relatedModelObjectGuid": "LI/CL/PO/r_physical/b876eefb0f288974/146956e90f8b5b6d/PO/eth/5979a210307b1e66/fba4016fb0ebde72",

  "additionTimeEpochMillis": 1668597718579,

  "description": "example",

  "validated": false,

  "validationResult": "UNKNOWN",

  "lastValidationCheck": 1668597744370,

  "conflicts": []

}

Add Manual Cross Link to Crosswork Hierarchical Controller

Use this API to add a manual cross link to Crosswork Hierarchical Controller.

Request Method

POST

Request URL

https://example-host/api/v2/crosslinks/manual

Request Parameters

None

Request Body

Request Body Example

{

  "interfaceA": {

    "deviceName": "CR2.BCN",

    "interfaceName": "TenGigE0/0/1/8"

  },

  "interfaceB": {

    "deviceName": "OTN1MIL01",

    "interfaceName": "1-2-3"

  },

  "technology": "ETH",

  "description": "example"

}

Response Example

{"guid":"d33ac2ec12c237e3a53bef30aec690e8f1ecff1a9c600c98b406ea9be30e91b7"}

Delete a Cross Link

Use this API to delete a manual cross link. The cross link is marked as deleted and is removed when the next validation runs.

Request Method

DELETE

Request URL

https://example-host/api/v2/crosslinks/manual/{guid}

Request Parameters

Response Example

200 OK

Shared Risk

Crosswork Hierarchical Controller provides APIs to administer shared risk policies and rules. 

You can access the Shared Risk API using Swagger: https://<host>/api/v2/apps/srlg-app/rest/doc

The APIs include:

●   Get a specific policy

●   Get all policies

●   Create a policy

●   Delete a policy

●   Change the shared risk type of the policy

●   Change a policy type

●   Add a new rule to a policy

●   Update the rule resources

●   Delete a rule from a policy

Get Policies

Use this API to get the list of all the policies. This returns a list of all the policies and their rules.

Request Method

GET

Request URL

https://example-host/api/v2/apps/srlg-app/rest/policy

Request Parameters

None

Response Example

{

    "name": "policy-1",

    "shared_risk_types": [

      "Link",

      "Port",

      "Card",

      "Shelf",

      "Device"

    ],

    "policy_type": "MULTIPLE-LINKS",

    "rules": [

      {

        "name": "rule-1",

        "resources": [

          "LI/eth/000fc44c94a1f2cd/51308dfd752c1574/df753d953c1e1c8f/f8e7b20537ce03b7"

        ]

      },

      {

        "name": "rule99",

        "resources": [

          "inventory[.name=\"CR1.PAR\"]|port|link[.layer=\"R_LOGICAL\"]"

        ]

      }

    ]

  },

  {

    "name": "test",

    "shared_risk_types": [

      "Link",

      "Device",

      "Shelf",

      "Port",

      "Card"

    ],

    "policy_type": "MULTIPLE-LINKS",

    "rules": [

      {

        "name": "rule001",

        "resources": [

          "inventory[.name=\"ILA-SD1EVO01-SD1SEV01-1\"]|port|link[.layer=\"R_LOGICAL\"]"

        ]

      }

    ]

  },

  {

    "name": "policy-3",

    "shared_risk_types": [

      "Link"

    ],

    "policy_type": "SINGLE-PROTECTED",

    "rules": [

      {

        "name": "rule-99",

        "resources": [

          "link[.layer=\"R_LOGICAL\"]"

        ]

      }

    ]

}

Get a Policy

Use this API to retrieve a policy.

Request Method

GET

Request URL

https:// example-host/api/v2/apps/srlg-app/rest/policy/{policyGuid}

Request Parameters

Response Example

{

  "name": "policy-1",

  "shared_risk_types": [

    "Link",

    "Port",

    "Card",

    "Shelf",

    "Device"

  ],

  "policy_type": "MULTIPLE-LINKS",

  "rules": [

    {

      "name": "rule-1",

      "resources": [

        "LI/eth/000fc44c94a1f2cd/51308dfd752c1574/df753d953c1e1c8f/f8e7b20537ce03b7"

      ]

    },

    {

      "name": "rule99",

      "resources": [

        "inventory[.name=\"CR1.PAR\"]|port|link[.layer=\"R_LOGICAL\"]"

      ]

    }

  ]

}

Create a Policy

Use this API to create a policy.

Request Method

POST

Request URL

https://example-host/api/v2/apps/srlg-app/rest/policy/{policyGuid}

Request Parameters

Request Body

Request Body Example

{

  "shared_risk_types": [

    "Link"

  ],

  "policy_type": "SINGLE-PROTECTED"

Response Example

201 Successful Operation

Delete Policy

Use this API to delete a policy.

Request Method

DELETE

Request URL

https://example-host/api/v2/apps/srlg-app/rest/policy/{policyGuid}

Request Parameters

Response Example

200 Successful

Update Policy Shared Risk Types

Use this API to change the policy shared risk types.

Request Method

PUT

Request URL

https://example-host/api/v2/apps/srlg-app/rest/policy/{policyGuid}/shared_risk_types

Request Parameters

Request Body

Request Body Example

{

  "shared_risk_types": [

    "Link"

  ]

}

Response Example

200 Successful Operation

Update Policy Type

Use this API to update credentials.

Request Method

PUT

Request URL

https://example-host/api/v2/apps/srlg-app/rest/policy/{policyGuid}/policy-type

Request Parameters

Request Body

Request Body Example

{

  "policy_type": "SINGLE-PROTECTED"

}

Response Example

200 Successful Operation

Add a Rule to a Policy

Use this API to add a rule to a policy. You can use an array of GUIDs and/or an SHQL query to create the rule.

Request Method

POST

Request URL

https://example-host/api/v2/apps/srlg-app/rest/policy/{policyGuid}/rules{ruleName}

Request Parameters

Request Body

Request Body Example

{

  "resources": [

    "link[.layer=\"R_LOGICAL\"]"

  ]

}

or

{

  "resources": [

    "LI/guid1",

    "LI/guid2"

  ]

}

or

{

  "resources": [

        "inventory[.name=\"CR1.PAR\"]|port|link[.layer=\"R_LOGICAL\"]"

   ]

}

Response Example

201 Successful Operation

Update a Rule

Use this API to update the rule's resources. You can use an array of GUIDs and/or an SHQL query to create the rule.

Request Method

PUT

Request URL

https://example-host/api/v2/apps/srlg-app/rest/policy/{policyGuid}/rules{ruleName}

Request Parameters

Request Body

Request Body Example

{

  "resources": [

    "link[.layer=\"R_LOGICAL\"]"

  ]

}

or

{

  "resources": [

    "LI/guid1",

    "LI/guid2"

  ]

}

or

{

  "resources": [

        "inventory[.name=\"CR1.PAR\"]|port|link[.layer=\"R_LOGICAL\"]"

   ]

}

Response Example

201 Successful Operation

Delete a Rule from a Policy

Use this API to delete a rule from a policy.

Request Method

DELETE

Request URL

https://example-host/api/v2/apps/srlg-app/rest/policy/{policyGuid} /policy/{policyGuid}/rules/{ruleName}

Request Parameters

Response Example

200 Successful

Root Cause Analysis

Crosswork Hierarchical Controller provides APIs to poll multi-layer Root Cause Analysis when a failure in optical layer impacts IP services.

You can access the Root Cause Analysis API using Swagger:

●       https://<host>/rca-app/public/rest/rca/doc

The APIs include:

●       GET /rest/rca/link: Get full list of failures with number of impacted services and impacted links.

●       GET /rest/rca/link/{link_guid:.*}: Get full list of services per specific failure.

GET /rest/rca/link

Use this API to perform root cause analysis on all the links and save the results to the cache for 60 seconds.

Request Method

GET

Request URL

https://example-host/rca-app/public/rest/rca/link

Request Parameters

None

Response Example

Note: This is a partial response for illustration purposes.

{

  "LI/lsp/ad789e8f8503819e/ad789e8f8503819e/7135255e84418d55/7135255e84418d55/lsp_1654182103797": {

    "affected_services": [],

    "affected_links": [],

    "affected_services_num": 0,

    "affected_links_num": 0

  },

  "LI/lsp/ad789e8f8503819e/ad789e8f8503819e/48435d75777086d4/48435d75777086d4/lsp_1654182103798": {

    "affected_services": [],

    "affected_links": [],

    "affected_services_num": 0,

    "affected_links_num": 0

  },

  "LI/och/018c725e75339c6c/c77fae729df95242/fa5c9008299c4a16/7882e64c50179230": {

    "affected_services": [],

    "affected_links": [

      {

        "name": "SD2BUC01/ETH-1-1-13 to SD2MOS01/ETH-1-1-10",

        "guid": "LI/eth/018c725e75339c6c/76949c8a55667088/fa5c9008299c4a16/ef10bbd4cdf77b48"

      },

      {

        "name": "SD2BUC01/ODU-1-1-13 to SD2MOS01/ODU-1-1-10",

        "guid": "LI/odu/018c725e75339c6c/b4a716060409d7e1/fa5c9008299c4a16/6afcb559c2e36e36"

      },

      {

        "name": "SD2BUC01/ODU-1-1-14 to SD2MOS01/ODU-1-1-11",

        "guid": "LI/odu/018c725e75339c6c/eac32c5f32ab783d/fa5c9008299c4a16/062a3e9a82d8d073"

      },

      {

        "name": "SD2BUC01/OTU-1-1-14 to SD2MOS01/OTU-1-1-11",

        "guid": "LI/otu/018c725e75339c6c/03da00b7867cfe5b/fa5c9008299c4a16/d02ab721880cb87c"

      }

    ],

    "affected_services_num": 0,

    "affected_links_num": 4

  },

  "LI/och/a9fa512f4169246f/df9e4b6ab4566374/1722e5a1036d6bfb/405abd491af01331": {

    "affected_services": [],

    "affected_links": [

      {

        "name": "CR1.COP/TenGigE0/0/1/6 to CR2.FRA/TenGigE0/0/3/3",

        "guid": "LI/r_physical/c0dda6439964c85a/2670ffd3c10f84f4/e8588ee29210274d/ac8df8ef371db594"

      },

      {

        "name": "SD1COP01/1-1-4 to SD1FRA01/2-4-4",

        "guid": "LI/eth/a9fa512f4169246f/a2fbc5a8b699f74c/1722e5a1036d6bfb/67da9c291405ffde"

      },

      {

        "name": "SD1COP01/1-1-4 to SD1FRA01/2-4-4",

        "guid": "LI/odu/a9fa512f4169246f/a2fbc5a8b699f74c/1722e5a1036d6bfb/67da9c291405ffde"

      },

      {

        "name": "SD1COP01/1-2-1 to SD1FRA01/2-5-1",

        "guid": "LI/odu/a9fa512f4169246f/df9e4b6ab4566374/1722e5a1036d6bfb/405abd491af01331"

      },

      {

        "name": "SD1COP01/1-2-1 to SD1FRA01/2-5-1",

        "guid": "LI/otu/a9fa512f4169246f/df9e4b6ab4566374/1722e5a1036d6bfb/405abd491af01331"

      }

    ],

    "affected_services_num": 0,

    "affected_links_num": 5

  },

"LI/mpls_tp/PO/mpls_tp/1df8ab6998bf7fc8/2670ffd3c10f84f4/3402c421ad0a46cda9e49c16f0269ab3/PO/mpls_tp/f38377d02bd88162/097f02fd45bfd9f5/83f6120a485f40c8b7114f5d153b41be/ce380dac1adc4194a2db15d339c2d7b8": {

    "affected_services": [

      {

        "name": "E-Line Packet Service <MPLS Domain E-Line 4>",

        "guid": "SV/MPLSDomainE-Line4"

      },

      {

        "name": "E-Line Packet Service <MPLS Domain E-Line 4>",

        "guid": "SV/MPLSDomainE-Line4"

      }

    ],

    "affected_links": [],

    "affected_services_num": 2,

    "affected_links_num": 0

  },

"LI/pseudo_wire/PO/virtual_uni/5e418f512277da7d/f437e03f8fa27767/e0eda1f05983496baf3a62f5ad07d1b7/1135/PO/virtual_uni/0a1e09ea95a0c199/9f441a08e4fa157c/396c1e2e9f5e4829bb8a196d0643da3d/2135": {

    "affected_services": [

      {

        "name": "E-Line Packet Service <IP Domain E-Line 3>",

        "guid": "SV/IPDomainE-Line3"

      }

    ],

    "affected_links": [],

    "affected_services_num": 1,

    "affected_links_num": 0

  }

GET /rest/rca/link/{link_guid:.*}

Use the API to get the root cause analysis for a single link from the cache (from the last 60 seconds) or generate the root cause analysis if the cache does not exist.

If no results are found the following may be returned:

●       404 not found: If the guid that does not exist in the entire network topology.

●       Empty JSON object {}: If the guid you specified exists, but there is no RCA created for the specific link.

Request Method

GET

Request URL

https://example-host/rca-app/public/rest/rca/link/{link_guid:.*}

Request Parameters

Response Example

{

  "affected_services": [],

  "affected_links": [

    {

      "name": "SR_P_600_reverse",

      "guid": "LI/sr_policy/igp/isis/default-domain/CR1.DUB/l2/router-id/100.0.0.1:igp/isis/default-domain/CR1.SPB/l2/router-id/100.0.0.123/14601"

    }

  ],

  "affected_services_num": 0,

  "affected_links_num": 1

}

 

Generic Information Retrieval using SHQL

Crosswork Hierarchical Controller provides a specialized query language designed for network data, called Sedona Hierarchical Query Language (SHQL). SHQL allows users to specify any query and quickly see the results, as well as to save the query for the benefit of others.

SHQL is unique in the way that it allows users to query a multi-layer model using simple keywords. Keywords allow for navigating the model, transitioning from one object type to another, and eliminating the need for complex conditions.

Transitioning is when SHQL allows for retrieving a list of objects and using this to transition to related objects, for example, retrieve all the SITES in the system and then use a language operator “|” (pipe operator) to get all INVENTORY in those sites etc.

For example, all OMSs used by a specific LSP can be retrieved using just a ‘downward’ command that retrieves, for the specified LSP, all links in the specified lower layer.

link[.name="my_lsp"] | downward ("OMS")

SHQL can be used in the UI application in Crosswork Hierarchical Controller or as REST POST commands.

Request Method

POST

Request URL

https://<server>/api/v2/shql

Request Example

In this example, the query gets the list of OMSs that are the underlay for all LSPs in operational state down.

link[.layer="LSP" and .operStatus="DOWN"] | downward | link[.layer="OMS" and .operStatus="DOWN"]

Response Example

{

    "activeProtectionPriority": null,

    "bidi": true,

    "desc": null,

    "distanceMeters": null,

    "extra": null,

    "guid": "LI/oms/af5e85ffc6049e8f/8c290fec341b62da/9bf4b791d3191519/3837d2f977f671bd",

    "inverseLinkId": null,

    "latencyMicros": null,

    "layer": "OMS",

    "name": "SD1BKL01/1-2-5&8 to SD1SLO01/1-3-5&8",

    "operStatus": "DOWN",

    "pathGroupType": "SINGLE_PATH",

    "paths": [

        {

            "guid": "PA/oms/af5e85ffc6049e8f/8c290fec341b62da/9bf4b791d3191519/3837d2f977f671bd"

        }

    ],

    "portA": {

        "guid": "PO/oms/af5e85ffc6049e8f/8c290fec341b62da",

        "type": "OMS"

    },

    "portB": {

        "guid": "PO/oms/9bf4b791d3191519/3837d2f977f671bd",

        "type": "OMS"

    },

    "protectionStatus": "N_A",

    "provider": "Topogen",

    "role": "REGULAR",

    "srlgs": null,

    "teMetric": null

}

Introducing SQHL

SHQL - The Need

Cisco Crosswork Hierarchical Controller provides valuable information on network structure and enables you to simulate various conditions using several dedicated applications.

You may, however, want to perform your own analytics and view the resulting reports.  Querying a multi-dimensional data model is complex and requires deep understanding of the model and advanced dev skills. For example:

●   Filter one layer by another

●   Get data from different times

●   Find anomalies

●       Group links by attributes in multiple dimensions

The model data is multi-dimensional and includes:

●   Vendors

●   Topologies

●   Layers

●   Domains

●   Status

●   Time

The SHQL application solves this problem by implementing cross-queries between the layers and dimension tables. It hides data complexity and provides a simple, yet powerful query language that enables you to easily query the model across all these dimensions.

SHQL Overview

The SHQL application enables you to quickly create complex query commands and send them as requests to the Crosswork Hierarchical Controller SHQL REST API. Accessed through your browser, the SHQL application allows you to run queries and view an orderly distribution of results under their relevant column headings. The type and number of columns are based on the properties of the object type displayed.

The application covers every functionality of the query language. Auto-completion context menus allow you to easily select viable object types and their related properties and apply multiple conditions using a range of operands.

SHQL allows you to manipulate the displayed information by transforming the query from one object type to another within the same query command line. Alternatively, you can specify a collection of object types to which all the query items are related.

Note:      The term object type used in this guide is defined as an item or group of items that share the same properties.

Crosswork Hierarchical Controller Object Model

SHQL Object Model

Inventory Types

Table 2.           Inventory Types

Link Types

Table 3.           Link Types

Crosswork Hierarchical Controller Connection Model

For example: 10GE over 100G OTN link

Connection Model

SQHL Example

This example finds if there are shared OMSs between two LSPs.

SHQL Example

Using SHQL

About the SHQL Interface

In your browser, open the SHQL application by clicking its button on the sidebar.

Note:      It is recommended that you use Chrome.

SHQL Application Button

The SHQL application interface is displayed. The field in which you insert your query is empty.

SHQL Interface

Once you have run a query, you can save it for future use (see Saving Queries).

Running Queries

To run a query:

1.     Enter a query command into the Query field (see Creating Queries).

2.     Click Run.

The retrieved data is organized under its related tabs.

Figure 6 shows a list of results under two tabs after running the query, inventory_item.

Query Screen with Inventory Item Results – Optical Node

Query Screen with Inventory Item Results – Routers

Clicking the … adjacent to the object in the GUID column displays its properties in JSON format. The .JSON lists the object’s properties and their values.

Inventory Object in .JSON Format

Aborting Queries

When you run a query that takes a long time to return results you can abort the query. 

To abort a query:

1.     Enter a query command into the Query field (see Creating Queries).

2.     Click Run. If the query will take a long time to return results, an abort option is offered.

Abort Query

3.     If you want to terminate the query, click Abort.

Creating Queries

You can build queries using free text, selecting an item from the auto-completion context menu or using a combination of both. The first item you enter into the Query field is an object type.

You can use the auto-completion context menu at any location in the query syntax.

Note:      Queries are not case sensitive.

To display an auto-completion context menu:

●   Click inside the Query field and then do one of the following:

◦        Mac: Press Command + spacebar

◦        PC: Press Ctrl + spacebar

The menu appears.

Figure 10 shows the object type auto-completion context menu.

Auto-completion Context Menu

Selecting an item from the menu displays it in the Query field. You can continue to build the query, adding conditions and functions.

Incorrect input - from either free text or context menu selection - is indicated by a red icon  . Hovering over the icon indicates why the input is not viable or suggests the expected input.

Input Not Viable

Sometimes, the error is a simple one of syntax, as in Figure 12.

Syntax Error

Note:      It is useful to look at the .JSON file of the queried object type to ascertain what input is viable.

Saving Queries

After creating a query, you can store it in the Saved Queries dropdown menu for repeated use.

To save a query:

1.     When you complete writing your query, click Save As.

The following dialog box appears.

Query Name Dialog Box

2.     Type a name for the query and click Save.

Saved Queries

3.     Repeat steps 1 and 2 for every query you want to save.

Deleting Queries

To delete a query:

1.     Select a query from the dropdown list of saved queries.

Deleting Queries

2.     Click Delete.

The query is removed from the list.

Sorting Columns

Retrieved data is displayed under the relevant column headings.

You can sort the items in ascending or descending order and apply filters to individual columns.

Note:      Column management is handled in the same way as other Crosswork Hierarchical Controller tables.

To sort columns:

1.     Click a column heading.

An upward pointing arrow appears.

Column Contents in Descending Order

2.     Click the arrow to sort the column items in ascending order. Click it again to sort the column items in descending order.

Column Contents in Ascending Order

To filter column contents:

1.     In the column heading, click the Filter icon.

The column heading expands to display filtering options.

Filter Column Contents

2.     Select an option value or type a pattern into the text box to filter the column contents. The column Filter icon changes to , indicating that a filter is applied to the column.

Filter Applied to Column

Creating Conditions

You can apply conditions to an object type, using the operands described in the table below.

Conditions are generally not case sensitive. Case must be adhered to only when it’s part of a predefined list of values.

Conditions are placed within square brackets([ ]).

Table 4.           Operands

Example 1: Filtering with Operands

Figure 20. retrieves a list of routers with names that begin with CR1.

Filtering Using Operand

Figure 21 shows the results.

Query Results

Example 2: Filtering with Operands

Figure 22 retrieves the inventory where the vendor is Ciena.

Filtering Using Operand

Figure 23 shows the results.

Query Results

Example 3: Filtering with Operands

Figure 24 looks for links where (port_a.guid = "PO/igp/06c0868cc5601e85/06c0868cc5601e85" and port_b.guid ="PO/igp/c3b0dc2cd3ad6406/c3b0dc2cd3ad6406") or (port_a.guid = "PO/igp/c3b0dc2cd3ad6406/c3b0dc2cd3ad6406" and port_b.guid = "PO/igp/06c0868cc5601e85/06c0868cc5601e85").

Filtering Using Operand

Figure 25 shows the results.

Query Results

Example 4: Filtering with Operands

Figure 26 retrieves and adds up the events captured the day before yesterday (>-2d and <-1d). The .timeStamp property can be used with d (days), h (hours), m (months), M (minutes). S (seconds), y (years) or w (weeks).

Filtering Using Operand

Figure 27 shows the results.

Query Results

Transforming/Collecting Object Types

You can add an object type to the query command and determine if the data to be retrieved is transformed from one object type to another object type, or if the data reflects a collection of multiple object types and their related items.

●       Transformation: Add a pipe (|) to the query command before adding the new object type. Transforms the results relating to the previous object type to output for the new object type.

●       Collection: Add an ampersand (&) to the query command before adding the new object type. Retrieves all the output for all the preceding object types.

●       As: Add a temporary variable. Enables you to create a query with an object type that is not related to the preceding object type.

The table describes object types and the object types to which they are directly related.

Table 5.           Object Types and Properties

Example: Object Types Transformation

Figure 28.Figure 28 shows a query built to retrieve ports belonging to the object type inventory item. The object types are separated by a pipe (|).

Query with Object Type Transformation

Figure 29 shows the results.

Transformation Results

Example: Object Types Collection

Figure 30 shows a query built to retrieve sites and the inventory items the sites belong to. The object types are separated by an ampersand (&).

Query with Object Type Collection

Figure 31 shows the results.

Collection Results

Example: As Temporary Variable

Using As allows you to use the output of a query as the input in collections.

The following figures demonstrate how to create a query built to support non-related object types using a temporary variable.

Figure 32 shows a query command composed of an object type, link.

Query

Figure 33 shows the results.

Query Results

Figure 34 shows how to create a temporary variable using As. The variable L appears in the context menu as a valid object type.

Adding As

Figure 35 shows how to use the temporary variable L to transform a list of links to their ports, paths and site links.

Query Using as

Figure 36 shows the results.

Results using Temporary Variable

Functions

SHQL provides several functions that allow you to precisely define the quantity, type and network layer of the items to retrieve.

Functions are preceded by a pipe in the query command line.

You can retrieve an item and then specify whether to retrieve related items from either above or below the layer, or from both above and below. These recursive operations are valid for port, link, site, inventory, and visual site.

Using Retrospective plus a timestamp enables you to query a situation that existed before the present time. For example, you can check the status of a site when it was down earlier in the day but in the present is up and running.

In addition, SHQL functions enable you to retrieve data based on free text.

SHQL functions are described in the table below.SHQL Functions

Table 6.           SHQL Functions

Example: downward Function

The following figures demonstrate how to create a query to retrieve items from all layers below a link, according to its GUID.

Figure 37 shows a query command composed of an object type followed by its GUID.

Query Command

Figure 38 shows the results.

GUID Results

Figure 39 shows nine additional items below the link layer, retrieved after adding the function downward to the command.

Results with the Function Downward

Example: retrospective Function

Figure 40 shows the query command built to retrieve the situation in the network at a specific time in the past.

You can use different time formats:

●       Absolute time: @2019-05-10 10:00:00

●       Relative time in the format '-'[0-9]+[ymwdHMS]: @-10H

●       Unix timestamp (ms): @1558610956000

@ and Epoch Timestamp

Figure 41 shows the results.

Timestamp Results

Example: group_by Function

Figure 42 shows the query command to group the devices by site (and count them).

group_by

Figure 23 shows the results.

group_by Results

History Function

Crosswork Hierarchical Controller keeps records of all changes in the network inventory and topology. The changes are stored as a list of events in an event history table. An event is a record of any resource addition (ADD), deletion (DELETE) or attribute change (UPDATE). The events are linked to the model using the guid as an index to the objects in the model. The events table includes all the details of the changes including the time, resource ID, object type, event type, and the value before and after the change.

A unique implementation was selected in order to include all resources that were in the model at some point in the selected time range in the returned results. Thus, it guarantees that services or links that were subsequently deleted are still found.  For example, if you query the table to get events for all services with specific tags for the past two weeks, the results will include the relevant services, including those that no longer exist at the end of the period. For more information, refer to the Crosswork Hierarchical Controller Network History Guide.

You can construct a query that uses a standard SHQL query to filter the model, then add the pipe (|) and filter the history table. The history table can be filtered by all the entry attributes:

●       Changed object guid

●       Changed object type

●       Change type (ADD, UPDATE, DELETE)

●       Value before

●       Value after

The results returned are from the event history table (whereas regular SHQL queries return results from the objects table).

Example: history

Figure 44 shows the query command built to retrieve the events for links between two dates.  You can narrow the query results by adding in the history table options, for example, only show UPDATE events, or search for links that went down.

@ and history

Figure 45 shows the results.

History Results

Additional Output Functions

You can add the functions described in the table below to retrieve results and display them in a specific order. Typically, these functions are added at the end of the query command. You can also view specific properties for the query results.

The function order is significant and must appear in the following order:

●       fibre talk set > view > operands > asc/desc > limit > after

For example:

●       This query is invalid: port | limit(10) | asc(.name)

●       This query is valid: port | asc(.name) | limit(10)

Output functions are preceded by a pipe (|).

Table 7.           Output Functions

Example: after

Figure 46 shows a query built to retrieve only items that follow the item with the specified GUID.

After Output Function

Figure 47 shows the results.

After Output Results

Example 1: add_counters

Figure 48 shows a query built to retrieve the total number of each of the link layers. Adding | limit (0) to the query limits the response to the counters only.

add_counters Function

Figure 49 shows the results.

add_counters Results

Example 2: add_counters

Figure 50 shows a query built to retrieve the total number of each of the link layers and the total number of links in each of the operational statuses (UP, DOWN or N_A). Adding | limit (0) to the query limits the response to the counters only.

add_counters Function

Figure 51 shows the results.

add_counters Results

Example 1: view

Figure 52 shows a query built to retrieve the port guid, name, device.name and teMetric for IGP ports.

View Output Function

Figure 53 shows the results.

View Output Results

Example 2: view

Figure 54 shows a query built to retrieve the link guid and the number of paths in the link, when the link is not in a FIBER or FIBER_SEGMENT layer.

View Output Function

Figure 55 shows the results.

View Output Results

Example 3: view

Figure 56 shows a query built to retrieve the link guid and port names when the link is not in a FIBER or FIBER_SEGMENT layer. The output is limited to 20 entries.

View Output Function

Figure 57 shows the results.

View Output Results

Example 4: view

Figure 58 shows a query built to count the hops for the specified path.

View Output Function

Figure 59 shows the results.

View Output Results

Complex Examples

Complex Example 1

The following figures demonstrate how to get OMS links that causes LSPs to fail. 

The query command includes the following:

site[.name="DUB"] | inventory_item | port | link[.layer="LSP"] as w; site[.name="BEL"] | inventory_item | port | link[.layer="LSP" and .guid in w] | downward("OMS") | link[.layer="OMS" and .operStatus="DOWN"]

Get all LPSs between sites DUB and BEL:

●       Use | to transform from one object type to another.

●       Use alias and in to reduce the list to only those between DUB to BEL.

Down to OMS links and filter by operational state:

●       Use ‘downward’ function.

●       Use layer name in function (downward (“OMS”)) to limit the downward to a specific level.

Query Results

Query Results

Complex Example 2

The following figures demonstrate how to get the current list of OMSs. 

The query command includes the following:

link[.name="CR1.DUB:CR1.BEL:lsp_0"] | downward | link[.layer="OMS"]

Get all OMSs used by specific LSP:

●       Get LSP by its name.

●       Downward to OMSs used by this LSP.

The query command that includes the following:

Query Command

Query Results

If you want to track the LSP path change over time, you can use for example, @-1d:

Query Command

Complex Example 3

The following figures demonstrate how to find shared risk between two IP links. 

The query command includes the following:

link[.name="10.40.0.157 to 10.40.0.158"] | downward | link[.layer="OMS"] as p; link[.name="10.40.0.154 to 10.40.0.153"] | downward | link[.layer="OMS"] as w; link[.guid in p and .guid in w]

Get OMSs of the first IP logical link:

●       Filter by link name, downward to its OMSs, and alias it as p.

Get OMSs of the second IP logical link:

●       Filter by link name, downward to its OMSs, and alias it as w.

Get all shared OMS links:

●       Get links that appear in both groups.

Query Command

Query Results

Complex Example 4

The following figures demonstrate how to find free ports for services in a site. 

The query command that includes the following:

site[.name contains "MIL"] | inventory_item | port[.type="ETH"] | link | port as p;  site[.name contains "MIL"] | inventory_item | port[.type="ETH" and .guid not in p]

Get all ETH ports of specific site used by links:

●       Get site ports, transform to links and then to ports, and alias it as p.

Get all ports that are not in use by links:

●       Get site ports, transform to ports, filter out those that appear in p.

Query Command

Query Results

Try It Yourself

Try and create your own complex query.

Figure 69 shows an example that includes:

●       Operands

●       Transformations

●       Collections

●       Functions

Complex Query

Table 8.           Breakdown of Complex Query

Figure 70 shows the results.

Complex Query Results

Use Time Machine

The time machine provides a snapshot of the state of the network as it was at a date in the past. In this mode, all applications reflect data and analysis that apply to this point in time.  By default you can view 365 days back in time.

You can use the time machine query the model as at a date in the past.

To change the model date:

1.     In the applications bar in Crosswork Hierarchical Controller, select SHQL.

2.     Click Live, select a date and click Confirm.

3.     Run the required query.

Object Type Properties

The following sections list all the properties aligned with the different object types.

Note: The alarm object is for use in future versions.

inventory_item Properties

Table 9.           inventory_item properties

port Properties

Table 10.       port properties

port_to_port Properties

Table 11.       Port_to_port properties

link Properties

Table 12.       link properties

site Properties

Table 13.       site properties

service Properties

Table 14.       service properties

service_intent Properties

Table 15.       service_intent properties

service_intent_domain_op Properties

Table 16.       Service_intent_domain_op properties

service_intent_resource Properties

Table 17.       service_intent_resource Properties

si_domain_op Properties

Table 18.       Service_intent_domain_op properties

event Properties

Table 19.       event properties

srlg Resource Properties

Table 20.       srlg properties

path Properties

Table 21.       path properties

site_link Properties

Table 22.       site_link properties

visual_site Properties

Table 23.       visual_site properties

inventory Properties

Table 24.       inventory properties

srlg_risk_resource_mtm Properties

Table 25.       srlg_risk_resource_mtm properties

risk_resource Properties

Table 26.       risk_resource properties

region Properties

Table 27.       region properties

history Properties

Table 28.       history properties

Dashboard

The Dashboard is made up of table, pie, chart, or custom widgets. The information presented in a widget is updated periodically, typically every few minutes. The dashboard is a 2D grid in which the widgets can be placed as desired.

There are also several builtin custom widgets:

●       Operationally Down Services: Shows the number of services which are not operational

●       RCA Impacted List: List of impacted links by current failures (maximum 10 entries).

●       Discovered Services: Shows the number of services discovered in the network.

●       PerformanceWidgetApp

●       SRLG Policy Violations: Shows SRLG policy violations.

●       Srlg Daily last run: Displays SRLG count between links types of the last run of Daily test.

●       Srlg Weekly last run: Displays SRLG count between links types of the last run of Weekly test.

Creating Widgets

You can create customized widgets, rapidly with no development efforts and no software delivery. The widget query runs when opening the Dashboard application and the widgets are displayed. The widget also has a refresh button to run the query manually.

The widget attributes are:

●       Title: The name of the SHQL widget as it appears in the SHQL Dashboard.

●       Type:

◦        Pie/bar – when the query contains counters only

◦        Graph – when the query contains timestamp and counters

◦        Table – when the query returns a list

●       Query: Guidance is provided according to the widget type selected.

◦        A Table or Pie widget query must include a View statement of no more than 5 fields. The results are limited to 100 items. For example:
port | view("Name": .name)

◦        A Graph widget query must include the add_counters rule, which adds the number of occurrences of each of the unique values of the specified field/s. There must be only 1 time-based field under the rule, which will be the desired data (like timestamps). For example:
event | add_counters(.timeStamp)

NOTE: timestamps in query should be in ISO format (YYYY-MM-DD hh:mm:ss)

●       ‘About’ text

●       Additional options that define if, and how, the widget will appear in the Dashboard.

To create a widget:

1.     In the applications bar in Crosswork Hierarchical Controller, select Dashboard.

2.     Select Widget Settings.

3.     Click + New SHQL Widget.

Creating New Widget

4.     Enter the Title.

5.     Select the Type. This can be Table, Graph, Pie, or Custom.

Creating New Widget

6.     Specify the SHQL Query.

7.     Specify the Size Multiplier. This sets the relative size of the widget as a multiplier of  a single widget size, determining the actual size in grid cells.

8.     Select whether the widget should be Visible in the dashboard.

9.     Select whether you wan to refresh the widget, and if so, how often (in minutes).

10.  Enter some information about your widget.

11.  Click Save.

 

Configuring Dashboard Settings

You can alter the dashboard size, capacity and visibility. Every widget occupies a single row by its height, and depending on its size can occupy multiple grid cells by its width. The size of a widget is a multiplier applied to a single widget size (meaning: actual_widget_size = single_widget_size_in_grid_cells * multiplier).

Dashboard Settings

●       Unit Height Px: A single dashboard grid cell height in pixels.

●       Unit Width Px: A single dashboard grid cell height in pixel.

●       Width Units: The amount of cells in a single dashboard grid row.

●       Unit Size: Amount of grid cells a single widget occupies by its width.

Appendix

Glossary