Cisco Crosswork Hierarchical Controller 10.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:

●        REST with JSON in body

●        REST with SHQL in body

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

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

●        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.

●        Service Manager: Various APIs to create and provision services.

●        Service Attachment Points: Provides information on the L2 and L3 network topology.

●        Status Change Notification Messages: Generates notification messages for various types of events.

●        PCE: Provides an API for calculating the path(s) for a Packet E-Line (PCE) service.

●        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.

API User Access

Each API endpoint requires a specific access permission. The required access for each endpoint is detailed in the API topics.

To add the permission for the user executing the API, in sedo run the command:

●        sedo security user set --access permission/hco/stats:ro USERNAME|GUID

Device Manager

Crosswork Hierarchical Controller provides APIs to administer device management. 

You can access the Device Manager API using Swagger:

●         https://<host>:<port>/device-manager-srv/public/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://<host>:<port>/device-manager-srv/public/rest/adapter

Request Access

permission/hco/device-manager-public-api:ro

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://<host>:<port>/device-manager-srv/public/rest/adapter/{adapterGuid}/adapter-schema

Request Access

permission/hco/device-manager-public-api:ro

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://<host>:<port>/device-manager-srv/public/rest/adapter/{adapterGuid}/device-schema

Request Access

permission/hco/device-manager-public-api:ro

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://<host>:<port>/device-manager-srv/public/rest/device?adapter={adapterGuid}

Request Access

permission/hco/device-manager-public-api:ro

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://<host>:<port>/device-manager-srv/public/rest/device

Request Access

permission/hco/device-manager-public-api:rw

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://<host>:<port>/device-manager-srv/public/rest/device/{deviceGuid}/adapters/
{adapterGuid}

Request Access

permission/hco/device-manager-public-api:rw

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://<host>:<port>/device-manager-srv/public/rest/device/{deviceGuid}/adapters/
{adapterGuid}

Request Access

permission/hco/device-manager-public-api:rw

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://<host>:<port>/device-manager-srv/public/rest/device/{deviceGuid}/adapters/
{adapterGuid}

Request Access

permission/hco/device-manager-public-api:rw

Request Parameters

Response Example

200 Successful

Update Device Name

Use this API to update the device name.

Request Method

PUT

Request URL

https://<host>:<port>/device-manager-srv/public/rest/device/{deviceGuid}/name/{name}

Request Access

permission/hco/device-manager-public-api:rw

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://<host>:<port>/device-manager-srv/public/rest/device{deviceGuid}/site

Request Access

permission/hco/device-manager-public-api:rw

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://<host>:<port>/device-manager-srv/public/rest/device/{deviceGuid}/status

Request Access

permission/hco/device-manager-public-api:ro

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://<host>:<port>/device-manager-srv/public/rest/device/{deviceGuid}

Request Access

permission/hco/device-manager-public-api:ro

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. The device is removed from the model, and the relevant related objects to this device will be removed:

●        All device inventory

●        All device topological ports

●        All port relations where one port in the relation belongs to the deleted device

●        All device topological links and paths

●        All topological paths where this device belong to a hop within them

●        All device SRLG resources

Request Method

DELETE

Request URL

https://<host>:<port>/device-manager-srv/public/rest/device/{deviceGuid}?force=true

Request Access

permission/hco/device-manager-public-api:rw

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://<host>:<port>/device-manager-srv/public/rest/credentials?type={type}

Request Access

permission/hco/device-manager-public-api:ro

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://<host>:<port>/device-manager-srv/public/rest/credentials/{name}

Request Access

permission/hco/device-manager-public-api:rw

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://<host>:<port>/device-manager-srv/public/rest/credentials/{name}

Request Access

permission/hco/device-manager-public-api:rw

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://<host>:<port>/device-manager-srv/public/rest/credentials/{name}

Request Access

permission/hco/device-manager-public-api:rw

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://<host>:<port>/device-manager-srv/public/rest/schema

Request Access

permission/hco/device-manager-public-api:ro

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 optical network elements/devices and their attributes, slots, cards, and ports.

This API supports optical devices only.

Get Devices

Use this API to get the list of all the optical network elements.

Request Method

GET

Request URL

https://<host>:<port>/network-inventory-app/public/rest/devices

Request Header

Accept: application/yang-data+json

Content-Type: application/yang-data+json

Response Example

{

  "optical_network_elements":[

    {

      "tid":"baf7f88c-1b12-3b47-aa00-a2b4d2a142f2"

    },

    {

      "tid":"7d53441d-c593-30b5-82ae-796b8435bc5a"

    },

    {

      "tid":"21239f28-80e9-392b-b7d6-f53a4852d84b"

    },

    {

      "tid":"bef23a19-ee58-3e43-9da6-bf794b144b1d"

    },

    {

      "tid":"381b1d12-9fb1-30f8-80cc-0b28b8e098d9"

    },

    {

      "tid":"d7829075-09ff-3625-8a73-40e5e0db91ad"

    },

    {

      "tid":"5810030f-e64a-33e4-a339-b5830fb66cef"

    },

    {

      "tid":"74a18469-7a84-38af-9e5d-87da07fc4b6b"

    },

    {

      "tid":"e335f315-91b2-3f4d-99ae-717397c72931"

    },

    {

      "tid":"ff822cae-cea9-36ea-9657-afa4e753e4c6"

    },

    {

      "tid":"f863f5d2-b430-3c97-8d8a-0e64915eca06"

    },

    {

      "tid":"9b46cf15-5008-3235-82e9-d6de4174916e"

    },

    {

      "tid":"78caa196-2282-3134-9e28-f44cecc0a283"

    },

    {

      "tid":"8906ee00-33a6-35c3-98d0-50cbca553f3a"

    }

  ]

}

Response Parameters

The response contains a list of the device inventory modules.

Get a Device

Use this API to get a specific device by its ID. You can specify whether to get a detailed device inventory or only its tid (full=true/false).

Request Method

GET

Request URL

https://<host>:<port>/network-inventory-app/public/rest/devices/{deviceGuid}?Full=true/false

Request Parameters

Query Parameters

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.

The /api/v2/timeseries/stats/ endpoint is not public. To use it, you must make it public and assign the correct permission.

1.     Run the following command:

kubectl get prj/hco -o yaml | yq 'with(.spec.services.brain.endpoints[] | select(.match | test("/api/v2/timeseries/stats\*")); .publicBaseUrl="/")' | kubectl replace -f -

2.     Verify that the change has taken effect by checking if the endpoint has publicBaseUrl: / under the endpoint.

3.     To add the permission for the user executing the API, in sedo run the command:

sedo security user set --access permission/hco/stats:ro USERNAME|GUID

4.     To test the API:

curl -ik -u <user>:<password>' https://<host>:<port>/api/v2/timeseries/stats/latest

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.

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 Access

permission/hco/stats:ro

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 Access

permission/hco/stats:ro

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 Access

permission/hco/stats:rw

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://<host>:<port>/api/v2/crosslinks/adjacencies

Request Access

permission/hco/crosslinks:ro

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

For example:

{

  "interfaceA":{

    "deviceName":"R1-PE",

    "interfaceName":"Port 1/1/c2/1",

    "type":"R_PHYSICAL",

    "guid":"PO/nokia-nsp-adpt/R1-PE/PHY-R1-PE:shelf=1/slot=1/card=1/slot=1/card=1/port=c2/port=1"

  },

  "interfaceB":{

    "deviceName":"R2-PE",

    "interfaceName":"Port 1/1/2",

    "type":"R_PHYSICAL",

    "guid":"PO/nokia-nsp-adpt/R2-PE/PHY-R2-PE:shelf=1/slot=1/card=1/slot=1/card=1/port=2"

  },

  "technology":"ETH",

  "relatedModelObjectGuid":"LI/R_PHY/PO/nokia-nsp-adpt/R1-PE/PHY-R1-PE:shelf=1/slot=1/card=1/slot=1/card=1/port=c2/port=1/PO/nokia-nsp-adpt/R2-PE/PHY-R2-PE:shelf=1/slot=1/card=1/slot=1/card=1/port=2"

}

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://<host>:<port>/api/v2/crosslinks/validate

Request Access

permission/hco/crosslinks:rw

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://<host>:<port>/api/v2/crosslinks/validate/{guid}

Request Access

permission/hco/crosslinks:rw

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: The manual cross-link matchs a cross-link discovered by the LLDP protocol or similar received from the domain controller.

◦       VALIDATED_BY_CORRELATION: The ports were found to be correlated, by the cross-mapper correlation algorithm using statistics collected.

◦       NOT_CORRELATED: The ports were found to be not correlated, by the cross-mapper correlation algorithm using statistics collected.

◦       INCONCLUSIVE: The ports were examined by the cross-mapper correlation algorithm using statistics collected,but the final result is inconclusive.

◦       UNKNOWN: There are not enough statistics or traffic to apply the cross-mapper correlation algorithm on these ports.

◦       CONFLICT: The manual cross-link conflicts with a cross-link discovered by the LLDP protocol or similar that was received from the domain controller (one or both ports of the manual link appear with another port discovered by the LLDP protocol).

●        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://<host>:<port>/api/v2/crosslinks/manual

Request Access

permission/hco/crosslinks:r0

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://<host>:<port>/api/v2/crosslinks/manual/{guid}

Request Access

permission/hco/crosslinks:r0

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://<host>:<port>/api/v2/crosslinks/manual

Request Access

permission/hco/crosslinks:rw

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://<host>:<port>/api/v2/crosslinks/manual/{guid}

Request Access

permission/hco/crosslinks:rw

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>:<port>/srlg-app/public/rest/doc

The APIs include:

●    Get all policies

●    Get a specific policy

●    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://<host>:<port>/srlg-app/public/rest/policy

Request Access

permission/hco/user

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://<host>:<port>/srlg-app/public/rest/policy/{policyGuid}

Request Access

permission/hco/user

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://<host>:<port>/srlg-app/public/rest/policy/{policyGuid}

Request Access

permission/hco/user

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://<host>:<port>/srlg-app/public/rest/policy/{policyGuid}

Request Access

permission/hco/user

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://<host>:<port>/srlg-app/public/rest/policy/{policyGuid}/shared_risk_types

Request Access

permission/hco/user

Request Parameters

Request Body

Request Body Example

{

  "shared_risk_types": [

    "Link"

  ]

}

Response Example

200 Successful Operation

Update Policy Type

Use this API to update policy type.

Request Method

PUT

Request URL

https://<host>:<port>/srlg-app/public/rest/policy/{policyGuid}/policy-type

Request Access

permission/hco/user

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://<host>:<port>/srlg-app/public/rest/policy/{policyGuid}/rules{ruleName}

Request Access

permission/hco/user

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://<host>:<port>/srlg-app/public/rest/policy/{policyGuid}/rules{ruleName}

Request Access

permission/hco/user

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://<host>:<port>/srlg-app/public/rest/policy/{policyGuid} /policy/{policyGuid}/rules/{ruleName}

Request Access

permission/hco/user

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>:<port>/rca-app/public/rest/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 RCA on All Links

Use this API to perform root cause analysis on all the links with status down, and save the results to the cache for 60 seconds. Get full list of failures with number of impacted services and impacted links.

Request Method

GET

Request URL

https://<host>:<port>/rca-app/public/rest/link

Request Access

permission/hco/read-only

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 RCA on Link

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. Get full list of services per specific failure.

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 Access

permission/hco/read-only

Request URL

https://<host>:<port>/rca-app/public/rest/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

}

Service Manager

Crosswork Hierarchical Controller provides APIs to create OTN Line, Packet E-line, Circuit E-LIne, and MPLS-TP tunnel service-intents, and provision OTN Lines, Packet E-Lines, Circuit E-LInes, and MPLS-TP tunnels on underlying controllers.  For more information, see the Cisco Crosswork Hierarchical Controller Service Provisioning Guide.

You can access the Service Manager API using Swagger:

●        https://<host>:8443/service-manager-app/public/rest/doc

The APIs include:

●    Get the list of the operations created by calling the create/update/delete service intent APIs

●    Get existing OTN Line service-intents and matching discovered services from underlying controllers

●    Create new OTN Line service-intents and provision a new OTN Line on underlying controllers

●    Update OTN Line service

●    Get existing Packet E-Line service-intents and matching discovered services from underlying controllers

●    Create new Packet E-Line service-intents and provision a new Packet E-Line on underlying controllers

●    Update Packet E-Line

●    Get existing Circuit E-Line service-intents and matching discovered services from underlying controllers

●    Create new Circuit E-Line service-intents and provision a new Circuit E-Line on underlying controllers

●    Update Circuit E-Line

●    Get existing MPLS-TP tunnel service-intents and matching discovered tunnel services from underlying controllers

●    Create new MPLS-TP tunnel service-intents and provision a new MPLS-TP tunnel on underlying controllers

●    Delete and unprovision an existing service intent of any type

GET /service-intent​/operation

Use this API to get the list of the operations created by calling the create/update/delete service intent APIs. This returns a list of the operations. You also can request a specific service intent or filter by failed, active, pending, and/or successful operations.

Request Method

GET

Request URL

https://<host>:<port>/service-manager-app/public/rest/service-intent/operation

Request Access

permission/hco/service-manager-public-api:ro

Request Parameters

None

Request Body Parameters

Request Body Example 1

{

  "operation-id": "c1a34e3b8a504a73aee93a69e136c005"

}

Request Body Example 2

{

  "pagination": {

    "last-guid": "c1a34e3b8a504a73aee93a69e136c005",

    "limit": 10

  },

  "filter": {

    "show-failed": false,

    "show-active": true,

    "show-pending": true,

    "show-successful": false

  },

  "sort": "ASC"

}

Response Example

{

  "operations": [

    {

      "operation-id": "c1a34e3b8a504a73aee93a69e136c005",

      "creation-date": "2024-02-13T07:06:00.815Z",

      "last-modification-date": "2024-02-13T07:06:00.815Z",

      "is-active": true,

      "source": "REST_API",

      "service-intent-guid": "SI/9c278145d24d42898e49ff0de",

      "discovered-service-guid": "SV/ip-link/SI/5c1796b462154d28",

      "operation-type": "CREATE",

      "operation-state": "DISCOVERY",

      "current-flow": {

        "flow-type": "NORMAL",

        "total-request-count": 6,

        "sent-request-count": 6

      }

    }

  ],

  "errors": []

}

GET /service-intent​/p2p​/otn-line

Use this API to retrieve existing OTN Line service-intents and matching discovered services from underlying controllers.

Request Method

GET

Request URL

https://<host>:<port>/service-manager-app/public/rest/service-intent/p2p/otn-line

Request Access

permission/hco/service-manager-public-api:ro

Request Parameters

None

Request Body Parameters

Request Body Example 1

{

  "service-intent-guid": "SI/9c278145d24d42898e49ff0de"

}

Request Body Example 2

{

  "pagination": {

    "last-guid": "SI/9c278145d24d42898e49ff0de",

    "limit": 10

  },

  "filter": {

    "show-active": true,

    "show-removed": false,

    "show-failed": false

  },

  "sort": "ASC"

}

Response Example

{

  "otn-lines": [

    {

      "name": "otn-line 1",

      "description": "Otn Line number 1",

      "customer-name": "John Doe",

      "end-points": {

        "port-a-guid": "PO/sip/epnm/IN/ONE/epnm/ncs2k-A/c3fd0/7a61",

        "port-b-guid": "PO/sip/epnm/IN/ONE/epnm/ncs2k-F/a7654/3433"

      },

      "service-capacity": "ODU_FLEX",

      "odu-flex": {

        "allocate-tributary-slots": 6

      },

      "protection-policy": {

        "protection": "PROTECTED_1_PLUS_1",

        "diversity-level": "AVOID_LINKS"

      },

      "path-computation-provider": "DOMAIN_CONTROLLER",

      "path-computation": {

        "optimization-goal": "MINIMIZE_ADMIN_COST",

        "constraints": {

          "include-resources": [

            {

              "link": {

                "linkguid": "LI/och/epnm/IN/ONE/epnm/ncs2k-X/af472/bc33",

                "direction": "A_TO_B"

              }

            }

          ],

          "exclude-resources": [

            {

              "node-guid": "IN/ONE/epnm/ncs2k-C"

            },

            {

              "node-guid": "IN/ONE/epnm/ncs2k-G"

            },

            {

              "node-guid": "IN/ONE/epnm/ncs2k-H"

            }

          ]

        }

      },

      "guid": "SI/976ea6e7365caafe030d115370",

      "operational": {

        "creation-date": "2024-02-13T07:26:01.926Z",

        "last-modification-date": "2024-02-13T07:26:01.926Z",

        "deployment-goal": "PROVISION",

        "is-active": true,

        "discovered-service": {

          "discovery-status": "FULLY_DISCOVERED",

          "deployment-state": "DEPLOYMENT_COMPLETE",

          "operational-status": "UP",

          "health-status": "OK"

        }

      }

    },

    {

      "name": "otn-line 2",

      "description": "Otn Line number 2",

      "customer-name": "Jane Doe",

      "end-points": {

        "port-a-guid": "PO/sip/epnm/IN/ONE/epnm/ncs2k-A/bf78a/2947",

        "port-b-guid": "PO/sip/epnm/IN/ONE/epnm/ncs2k-F/4b3d0/187a"

      },

      "service-capacity": "ODU2E",

      "protection-policy": {

        "protection": "UNPROTECTED"

      },

      "explicit-path": {

        "hops": [

          {

            "link-guid": "LI/och/epnm/IN/ONE/epnm/ncs2k-A/73172/aaa3",

            "direction": "A_TO_B"

          }

        ]

      },

      "guid": "SI/9c278145d24d42898e49ff0de",

      "operational": {

        "creation-date": "2024-02-10T17:06:01.112Z",

        "last-modification-date": "2024-02-10T17:06:01.112Z",

        "deployment-goal": "PROVISION",

        "is-active": true,

        "discovered-service": {

          "discovery-status": "FULLY_DISCOVERED",

          "deployment-state": "DEPLOYMENT_COMPLETE",

          "operational-status": "UP",

          "health-status": "OK"

        }

      }

    }

  ]

}

POST /service-intent​/p2p​/otn-line

Use this API to create new OTN Line service-intents and provision a new OTN Line on underlying controllers.

Request Method

POST

Request URL

https://<host>:<port>/service-manager-app/public/rest/service-intent/p2p/otn-line

Request Access

permission/hco/service-manager-public-api:rw

Request Parameters

None

Request Body Parameters

Check the OtnLineService schema for more details such as mandatory options.

Request Body Example

{

  "name": "otn-line 1",

  "description": "Otn Line number 1",

  "customer-name": "John Doe",

  "end-points": {

    "port-a-guid": "PO/sip/epnm/IN/ONE/epnm/ncs2k-A/c3fd0/7a61",

    "port-b-guid": "PO/sip/epnm/IN/ONE/epnm/ncs2k-F/a7654/3433"

  },

  "service-capacity": "ODU_FLEX",

  "odu-flex": {

    "allocate-tributary-slots": 6

  },

  "protection-policy": {

    "protection": "PROTECTED_1_PLUS_1",

    "diversity-level": "AVOID_LINKS"

  },

  "path-computation-provider": "DOMAIN_CONTROLLER",

  "primary-path": {

    "path-computation": {

      "optimization-goal": "MINIMIZE_ADMIN_COST",

      "constraints": {

        "include-resources": [

          {

            "link": {

              "linkguid": "LI/och/epnm/IN/ONE/epnm/ncs2k-X/af472/bc33",

              "direction": "A_TO_B"

            }

          }

        ],

        "exclude-resources": [

          {

            "node-guid": "IN/ONE/epnm/ncs2k-C"

          },

          {

            "node-guid": "IN/ONE/epnm/ncs2k-G"

          },

          {

            "node-guid": "IN/ONE/epnm/ncs2k-H"

          }

        ]

      }

    }

  },

  "protection-path": {

    "explicit-path": {

      "hops": [

        {

          "link-guid": "LI/och/epnm/IN/ONE/epnm/ncs2k-A/73172/aaa3",

          "direction": "A_TO_B"

        }

      ]

    }

  }

}

Response Example

{

  "operation-id": "eb6fd5c971575497bb117b5fde22f9ad",

  "service-intent-guid": "SI/976ea6e7365caafe030d115370"

}

PATCH /service-intent​/p2p​/otn-line

Use this API to update the provisioned OTN Line.

Request Method

PATCH

Request URL

https://<host>:<port>/service-manager-app/public/rest/service-intent/p2p/otn-line

Request Access

permission/hco/service-manager-public-api:rw

Request Parameters

None

Request Body Parameters

The request body parameters are the same as those for POST /service-intent​/p2p​/otn-line.

To make a change, use GET /service-intent​/p2p​/otn-line to retrieve the service details and update the parameters that may be changed.

The following parameters may be updated in the CHANGE request.

GET /service-intent​/p2p​/packet-eline

Use this API to retrieve existing Packet e-Line service-intents and matching discovered services from underlying controllers.

Request Method

GET

Request Access

permission/hco/service-manager-public-api:ro

Request URL

https://<host>:<port>/service-manager-app/public/rest/service-intent/p2p/packet-eline

Request Parameters

None

Request Body Parameters

Request Body Example 1

{

  "service-intent-guid": "SI/9c278145d24d42898e49ff0de"

}

Request Body Example 2

{

  "pagination": {

    "last-guid": "SI/9c278145d24d42898e49ff0de",

    "limit": 10

  },

  "filter": {

    "show-active": true,

    "show-removed": false,

    "show-failed": false

  },

  "sort": "ASC"

}

Response Example

{

  "packet-elines": [

    {

      "name": "packet-eline 1",

      "end-points": {

        "port-a": {

          "port-guid": "PO/r_phy/mcp/IN/mcp/6500-A/e681/e557",

          "c-tag": {

            "vlan-id": 5

          }

        },

        "port-b": {

          "port-guid": "PO/r_phy/mcp/IN/mcp/6500-B/81d7/2319",

          "untagged": {}

        }

      },

      "underlay-tech": "MPLS_TP",

      "auto-bind": {},

      "guid": "SI/d8d0cc52aa5d3ebac509b93c3",

      "operational": {

        "creation-date": "2024-02-13T01:16:01.926Z",

        "last-modification-date": "2024-02-13T01:16:01.926Z",

        "deployment-goal": "PROVISION",

        "is-active": true,

        "discovered-service": {

          "discovery-status": "FULLY_DISCOVERED",

          "deployment-state": "DEPLOYMENT_COMPLETE",

          "operational-status": "UP",

          "health-status": "OK"

        }

      }

    },

    {

      "name": "packet-eline 2",

      "end-points": {

        "port-a": {

          "port-guid": "PO/r_phy/mcp/IN/mcp/6500-A/027d/d450",

          "c-tag": {

            "vlan-id-ranges": "100-200,300"

          }

        },

        "port-b": {

          "port-guid": "PO/r_phy/mcp/IN/mcp/6500-B/fc19/d3cd",

          "c-tag": {

            "vlan-id-ranges": "100-200,300"

          }

        }

      },

      "underlay-tech": "MPLS_TP",

      "manual-bind": {

        "tunnel-guids": [

          "LI/lsp/mcp/mpls-tp/cc72c9b58c612b7360a62fb480ff54cc"

        ]

      },

      "guid": "SI/a2536e681e5570567b0b918f1",

      "operational": {

        "creation-date": "2024-02-13T11:11:01.222Z",

        "last-modification-date": "2024-02-13T11:11:01.222Z",

        "deployment-goal": "PROVISION",

        "is-active": true,

        "discovered-service": {

          "discovery-status": "FULLY_DISCOVERED",

          "deployment-state": "DEPLOYMENT_COMPLETE",

          "operational-status": "UP",

          "health-status": "OK"

        }

      }

    }

  ]

}

No links

POST /service-intent​/p2p​/packet-eline

Use this API to create new Packet E-line service-intents and provision a new Packet E-Line on underlying controllers.

Request Method

POST

Request URL

https://<host>:<port>/service-manager-app/public/rest/service-intent/p2p/packet-eline

Request Access

permission/hco/service-manager-public-api:rw

Request Parameters

None

Request Body Parameters

Check the PacketElineService schema for more details such as mandatory options.

Request Body Example

{

  "name": "packet-eline 1",

  "end-points": {

    "port-a": {

      "port-guid": "PO/r_phy/mcp/IN/mcp/6500-A/e681/e557",

      "rate-limiting": {

        "cir": 2

      },

      "c-tag": {

        "vlan-id": 5

      }

    },

    "port-b": {

      "port-guid": "PO/r_phy/mcp/IN/mcp/6500-B/81d7/2319",

      "rate-limiting": {

        "cir": 1

      },

      "untagged": {}

    }

  },

  "underlay-tech": "MPLS_TP",

  "auto-bind": {}

}

Response Example

{

  "operation-id": "0f436a133299d0520b6d2d0bbe46ef41",

  "service-intent-guid": "SI/d8d0cc52aa5d3ebac509b93c3"

}

PATCH /service-intent​/p2p​/packet-eline

Use this API to update the Packet E-line service.

Request Method

PATCH

Request URL

https://<host>:<port>/service-manager-app/public/rest/service-intent/p2p/packet-eline

Request Access

permission/hco/service-manager-public-api:rw

Request Parameters

None

Request Body Parameters

The request body parameters are the same as those for POST /service-intent​/p2p​/packet-eline.

To make a change, use GET /service-intent​/p2p​/packet-eline to retrieve the service details and update the parameters that may be changed.

The following parameters may be updated in the CHANGE request.

GET /service-intent​/p2p​/circuit-eline

Use this API to retrieve existing Circuit E-Line service-intents and matching discovered services from underlying controllers.

Request Method

GET

Request URL

https://<host>:<port>/service-manager-app/public/rest/service-intent/p2p/circuit-eline

Request Access

permission/hco/service-manager-public-api:ro

Request Parameters

None

Request Body Parameters

Request Body Example 1

{

  "service-intent-guid": "SI/9c278145d24d42898e49ff0de"

}

Request Body Example 2

{

  "pagination": {

    "last-guid": "SI/9c278145d24d42898e49ff0de",

    "limit": 10

  },

  "filter": {

    "show-active": true,

    "show-removed": false,

    "show-failed": false

  },

  "sort": "ASC"

}

Response Example

{

  "otn-lines": [

    {

      "name": "circuit-eline 1",

      "description": "Circuit Eline number 1",

      "customer-name": "John Doe",

      "end-points": {

        "port-a-guid": "PO/sip/epnm/IN/ONE/epnm/ncs2k-A/c3fd0/7a61",

        "port-b-guid": "PO/sip/epnm/IN/ONE/epnm/ncs2k-F/a7654/3433"

      },

      "service-capacity": "CAPACITY_1GB",

      "underlay": "ODU_FLEX",

      "odu-flex": {

        "allocate-tributary-slots": 6

      },

      "protection-policy": {

        "protection": "PROTECTED_1_PLUS_1",

        "diversity-level": "AVOID_LINKS"

      },

      "path-computation-provider": "DOMAIN_CONTROLLER",

      "path-computation": {

        "optimization-goal": "MINIMIZE_ADMIN_COST",

        "constraints": {

          "include-resources": [

            {

              "link": {

                "linkguid": "LI/och/epnm/IN/ONE/epnm/ncs2k-X/af472/bc33",

                "direction": "A_TO_B"

              }

            }

          ],

          "exclude-resources": [

            {

              "node-guid": "IN/ONE/epnm/ncs2k-C"

            },

            {

              "node-guid": "IN/ONE/epnm/ncs2k-G"

            },

            {

              "node-guid": "IN/ONE/epnm/ncs2k-H"

            }

          ]

        }

      },

      "guid": "SI/976ea6e7365caafe030d115370",

      "operational": {

        "creation-date": "2024-02-13T07:26:01.926Z",

        "last-modification-date": "2024-02-13T07:26:01.926Z",

        "deployment-goal": "PROVISION",

        "is-active": true,

        "discovered-service": {

          "discovery-status": "FULLY_DISCOVERED",

          "deployment-state": "DEPLOYMENT_COMPLETE",

          "operational-status": "UP",

          "health-status": "OK"

        }

      }

    },

    {

      "name": "circuit-eline 2",

      "description": "Circuit Eline number 2",

      "customer-name": "Jane Doe",

      "end-points": {

        "port-a-guid": "PO/sip/epnm/IN/ONE/epnm/ncs2k-A/bf78a/2947",

        "port-b-guid": "PO/sip/epnm/IN/ONE/epnm/ncs2k-F/4b3d0/187a"

      },

      "service-capacity": "CAPACITY_40GB",

      "underlay": "ODU_FIX",

      "protection-policy": {

        "protection": "UNPROTECTED"

      },

      "explicit-path": {

        "hops": [

          {

            "link-guid": "LI/och/epnm/IN/ONE/epnm/ncs2k-A/73172/aaa3",

            "direction": "A_TO_B"

          }

        ]

      },

      "guid": "SI/9c278145d24d42898e49ff0de",

      "operational": {

        "creation-date": "2024-02-10T17:06:01.112Z",

        "last-modification-date": "2024-02-10T17:06:01.112Z",

        "deployment-goal": "PROVISION",

        "is-active": true,

        "discovered-service": {

          "discovery-status": "FULLY_DISCOVERED",

          "deployment-state": "DEPLOYMENT_COMPLETE",

          "operational-status": "UP",

          "health-status": "OK"

        }

      }

    }

  ]

}

POST /service-intent​/p2p​/circuit-eline

Use this API to create new Circuit E-Line service-intents and provision a new Circuit E-Line on underlying controllers.

Request Method

POST

Request URL

https://<host>:<port>/service-manager-app/public/rest/service-intent/p2p/circuit-eline

Request Access

permission/hco/service-manager-public-api:rw

Request Parameters

None

Request Body Parameters

Check the CircuitElineService schema for more details such as mandatory options.

Request Body Example

{

  "name": "circuit-eline 1",

  "description": "Circuit Eline number 1",

  "customer-name": "John Doe",

  "end-points": {

    "port-a-guid": "PO/sip/epnm/IN/ONE/epnm/ncs2k-A/c3fd0/7a61",

    "port-b-guid": "PO/sip/epnm/IN/ONE/epnm/ncs2k-F/a7654/3433"

  },

  "service-capacity": "CAPACITY_1GB",

  "underlay": "ODU_FLEX",

  "odu-flex": {

    "allocate-tributary-slots": 6

  },

  "protection-policy": {

    "protection": "PROTECTED_1_PLUS_1",

    "diversity-level": "AVOID_LINKS"

  },

  "path-computation-provider": "DOMAIN_CONTROLLER",

  "primary-path": {

    "path-computation": {

      "optimization-goal": "MINIMIZE_ADMIN_COST",

      "constraints": {

        "include-resources": [

          {

            "link": {

              "link-guid": "LI/och/epnm/IN/ONE/epnm/ncs2k-X/af472/bc33",

              "direction": "A_TO_B"

            }

          }

        ],

        "exclude-resources": [

          {

            "node-guid": "IN/ONE/epnm/ncs2k-C"

          },

          {

            "node-guid": "IN/ONE/epnm/ncs2k-G"

          },

          {

            "node-guid": "IN/ONE/epnm/ncs2k-H"

          }

        ]

      }

    }

  },

  "protection-path": {

    "explicit-path": {

      "hops": [

        {

          "link-guid": "LI/och/epnm/IN/ONE/epnm/ncs2k-A/73172/aaa3",

          "direction": "A_TO_B"

        }

      ]

    }

  }

}

Response Example

{

  "operation-id": "eb6fd5c971575497bb117b5fde22f9ad",

  "service-intent-guid": "SI/976ea6e7365caafe030d115370"

}

PATCH /service-intent​/p2p​/circuit-eline

Use this API to update the Circuit E-line service.

Request Method

PATCH

Request URL

https://<host>:<port>/service-manager-app/public/rest/service-intent/p2p/circuit-eline

Request Access

permission/hco/service-manager-public-api:rw

Request Parameters

None

Request Body Parameters

The request body parameters are the same as those for POST /service-intent​/p2p​/circuit-eline.

To make a change, use GET /service-intent​/p2p​/circuit-eline to retrieve the service details and update the parameters that may be changed.

The following parameters may be updated in the CHANGE request.

GET /service-intent​/tunnel​/mpls-tp

Use this API to retrieve existing MPLS-TP tunnel service-intents and matching discovered tunnel services from underlying controllers.

Request Method

GET

Request URL

https://<host>:<port>/service-manager-app/public/rest/service-intent/tunnel/mpls-tp

Request Access

permission/hco/service-manager-public-api:ro

Request Parameters

None

Request Body Parameters

Request Body Example 1

{

  "service-intent-guid": "SI/9c278145d24d42898e49ff0de"

}

Request Body Example 2

{

  "pagination": {

    "last-guid": "SI/9c278145d24d42898e49ff0de",

    "limit": 10

  },

  "filter": {

    "show-active": true,

    "show-removed": false,

    "show-failed": false

  },

  "sort": "ASC"

}

Response Example

{

  "mpls-tp-tunnels": [

    {

      "name": "mpls-tp-service",

      "end-points": {

        "ports": {

          "port-a-guid": "PO/sip/mcp/IN/mcp/6500-A/8405/9f2b",

          "port-b-guid": "PO/sip/mcp/IN/mcp/6500-B/986d/f54d",

          "backup": {

            "port-a-guid": "PO/sip/mcp/IN/mcp/6500-A/69bb/0ed2",

            "port-b-guid": "PO/sip/mcp/IN/mcp/6500-B/3f37/a960"

          }

        }

      },

      "reserved-bandwidth-mbps": 500,

      "path-computation-provider": "DOMAIN_CONTROLLER",

      "path-computation": {

        "optimization-goal": "MINIMIZE_ADMIN_COST"

      },

      "guid": "SI/80410ac9a631cb0ed911d7fa",

      "operational": {

        "creation-date": "2024-01-25T17:12:11.456Z",

        "last-modification-date": "2024-01-15T17:12:11.456Z",

        "deployment-goal": "PROVISION",

        "is-active": true,

        "discovered-service": {

          "discovery-status": "FULLY_DISCOVERED",

          "deployment-state": "DEPLOYMENT_COMPLETE",

          "operational-status": "UP",

          "health-status": "OK"

        }

      }

    }

  ]

}

 

POST /service-intent​/tunnel/mpls-tp

Use this API to create new MPLS-TP tunnel service-intents and provision a new MPLS-TP tunnel on underlying controllers.

Request Method

POST

Request URL

https:// <host>:<port>/service-manager-app/public/rest/service-intent/tunnel/mpls-tp

Request Access

permission/hco/service-manager-public-api:rw

Request Parameters

None

Request Body Parameters

Check the MplsTpService schema for more details such as mandatory options.

Request Body Example

 

  "name": "mpls-tp-service",

  "end-points": {

    "ports": {

      "port-a-guid": "PO/sip/mcp/IN/mcp/6500-A/8405/9f2b",

      "port-b-guid": "PO/sip/mcp/IN/mcp/6500-B/986d/f54d",

      "backup": {

        "port-a-guid": "PO/sip/mcp/IN/mcp/6500-A/69bb/0ed2",

        "port-b-guid": "PO/sip/mcp/IN/mcp/6500-B/3f37/a960"

      }

    }

  },

  "reserved-bandwidth-mbps": 500,

  "path-computation": {}

}

Response Example

{

  "operation-id": "a8f6ff1198563bb85049a469c280f422",

  "service-intent-guid": "SI/80410ac9a631cb0ed911d7fa"

}

DELETE /service-intent/

Use this API to delete and unprovision an existing service intent of any type.

Request Method

DELETE

Request URL

https:// <host>:<port>/service-manager-app/public/rest/service-intent/

Request Access

permission/hco/service-manager-public-api:rw

Request Parameters

None

Request Body Parameters

Request Body Example 1

{

  "service-intent-guid": "SI/9c278145d24d42898e49ff0de"

}

Response Example

{

  "operation-id": "b7961fede11f7b98444110cb2fb5d183"

}

 

Service Attachment Points

The Service Attachment Points (SAP) API provides information on the L2 and L3 network topology including the following service-types:

●        L3 VPN: ietf-vpn-common:l3vpn

●        E-LINE: ietf-vpn-common:vpws

●        L2 VPN (vpls): ietf-vpn-common:vpls

●        L2 VPN (evpn): ietf-vpn-common:vpws-evpn

Note: E-LINE is a type of L2 VPN.

Create SAP Key Tags

The SAP API requires you to tag the device interface objects in the Model Settings application.

You need to create L2VPN or L3VPN tags, including a filter based on the ports.

The following port types are supported:

●        R_PHYSICAL

●        R_AGGREGATE

●        UNI

●        VIRTUAL_UNI

●        R_LOGICAL (for loopback ports omly)

Note: You may use the SHQL Query application to test the query used in the filter prior to creating the tags.

Table 1.        Query Examples

 

To create the SAP tagging:

1.     Use SHQL Query to test your tagging filter.

2.     In the Model Settings application, in the Tags tab, create a SAP key.

3.     Create the L2VPN or L3VPN tags (in ALL CAPS), adding the filter in the Rule Editor. The default recommended filter is:
port[.type="R_PHYSICAL"]

Get Help

Use this API to get help on the SAP API.

Request Method

GET

Request URL

https://{{sap.url}}:{{sap.port}}/sap-srv/public/help

Request Access

permission/hco/sap-srv:ro

Request Header

Accept: application/yang-data+json

Content-Type: application/yang-data+json

Response Example

{

    "/sap-srv/public/ietf-sap-ntw": {

        "description": "Returns a list of all SAPs according to the existing SAP query in the model settings application",

        "parameters": {

            "service-type (optional)": "filter parameter - The type of service (optional), can either be 'l2vpn' or 'l3vpn'",

            "router-count (optional)": "pagination parameter - The number of routers to collect. If not given SAPs from all routers will be returned",

            "starting-router-guid (optional) ": "pagination parameter - The GUID of the router you want to start collecting from, if doesn't exist you'll start from the first router (sorted lexicographically)"

        },

        "other notes": [

            "If starting-router-guid is not given (usually the first request in pagination), the number of routers with saps will also be returned.In order to use pagination, use the returned 'next-router-guid' value in the response as your next starting-router-guid"

        ]

    }

}

Response Parameters

The response contains help text.

Get SAPS

Use this API to get a list of all SAP items tagged as L2VPN or L3VPN in the Model Settings application. You can specify how many routers to return and from which router guid onwards to list the SAPs.

Request Method

GET

Request URL

https://{{sap.url}}:{{sap.port}}/sap-srv/public/ietf-sap-ntw?service-type={{service-type}}&router-count={{sap.router_count}}&starting-router-guid={{sap.starting_router_guid}}

Request Access

permission/hco/sap-srv:ro

Request Parameters

Request Header

Accept: application/yang-data+json

Content-Type: application/yang-data+json

Request Example

https://{{sap.url}}:{{sap.port}}/sap-srv/public/ietf-sap-ntw?router-count={{sap.router_count}}

https://{{sap.url}}:{{sap.port}}/sap-srv/public/ietf-sap-ntw?router-count={{sap.router_count}}&starting-router-guid={{sap.starting_router_guid}}

https://{{sap.url}}:{{sap.port}}/sap-srv/public/ietf-sap-ntw?service-type=l2vpn

Response Example

This response example has 9 routers in total and includes the following service types:

●        ietf-vpn-common:l3vpn

●        ietf-vpn-common:vpls

●        ietf-vpn-common:vpws

●        ietf-vpn-common:vpws-evpn

Each service-type includes the related sap items. For example:

"sap":[

            {

              "sap-id":"PO/cisco-cnc-adpt/AGG-P-BOTTOMLEFT:Bundle-Ether100",

              "attachment-interface":"Bundle-Ether100",

              "interface-type":"ietf-sap-ntw:phy",

              "role":"ietf-sap-ntw:uni",

              "allows-child-saps":true,

              "sap-status":{

                "status":"ietf-vpn-common:op-down"

              },

              "encapsulation-type":"ietf-vpn-common:ethernet-type",

              "description":"lag to P-BOTTOMMID"

            },

            {

              "sap-id":"PO/cisco-cnc-adpt/LGC-P-BOTTOMLEFT:Loopback0",

              "attachment-interface":"Loopback0",

              "interface-type":"ietf-sap-ntw:loopback",

              "role":"ietf-sap-ntw:uni",

              "allows-child-saps":false,

              "sap-status":{

                "status":"ietf-vpn-common:op-up"

              },

              "description":"Loopback"

            },

...

 

Status Change Notification Messages

Crosswork Hierarchical Controller generates notification messages for various types of events:

●        Service Assurance​:

◦       Service UNIs  admin/oper status change​

◦       Service health status change​

◦       Service deployment status change​

●        Model Changes:​

◦       Link admin/oper status change​

Table 2.        Supported Service Types

 

Each event has a change-id that is monotonically increasing. Also known as cursor-id.

A change-id may have multiple events. For example, a model change operation may have a single change-id but many  events (for example, ports and links creation).  

Example of a change-id with multiple events:

Note: Some change-ids in the system are not relevant and therefore not visible to the end user.

Notifications Structure

The service-changes notifications are defined as follows:

    +---n service-changes
    |  +--ro service-change-type             enumeration
    |  +--ro name?                           string
    |  +--ro guid                            string
    |  +--ro action                          action-type
    |  +--ro change-id                       uint32
    |  +--ro service-type?                   service-type
    |  +--ro port-type?                      port-type
    |  +--ro (event)?
    |     +--:(port-admin-status)
    |     |  +--ro portAdminStatus
    |     |     +--ro name?          string
    |     |     +--ro guid           string
    |     |     +--ro action         action-type
    |     |     +--ro change-id      uint32
    |     |     +--ro type?          port-type
    |     |     +--ro device?        string
    |     |     +--ro site?          string
    |     |     +--ro adminStatus    hco-common:port-admin-status
    |     +--:(port-oper-status)
    |     |  +--ro portOperStatus
    |     |     +--ro name?         string
    |     |     +--ro guid          string
    |     |     +--ro action        action-type
    |     |     +--ro change-id     uint32
    |     |     +--ro type?         port-type
    |     |     +--ro device?       string
    |     |     +--ro site?         string
    |     |     +--ro operStatus    hco-common:port-oper-status
    |     +--:(service-health-status)
    |     |  +--ro serviceHealthStatus
    |     |     +--ro healthStatus    hco-common:service-health-status
    |     +--:(service-deployment-state)
    |     |  +--ro serviceDeploymentState
    |     |     +--ro deploymentState    hco-common:service-deployment-state
    |     +--:(service-oper-state)
    |        +--ro serviceOperState
    |           +--ro operationalStatus    hco-common:service-oper-status
The model-changes notifications are defined as follows:

    +---n model-changes
    |  +--ro name?                   string
    |  +--ro guid                    string
    |  +--ro action                  action-type
    |  +--ro change-id               uint32
    |  +--ro type?                   link-layer
    |  +--ro model-change-type       enumeration
    |  +--ro (event)?
    |     +--:(link-oper-status)
    |     |  +--ro linkOperStatus
    |     |     +--ro operStatus    hco-common:link-oper-status

For example:

 

 

Get Change ID

Use this API to get the change-id. This is the most recent change-id in the system.

Request Method

GET

Request URL

https://<host>:<port>/restconf-notification-srv/restconf/operations/hco-notification:get-change-id ​

Request Access

permission/hco/restconf-notification-srv:ro

Request Parameters

None

Request Header

Accept: application/yang-data+json

Content-Type: application/yang-data+json

Response Example

Register to Notification Streams

You can register to the service changes or model changes notification stream.

Request Method

GET

Request URL

https://<host>:<port>/restconf-notification-srv/restconf/data/ietf-restconf-monitoring:restconf-state/streams/stream={changeType}/access={accessFormat}/location

Request Access

permission/hco/restconf-notification-srv:ro

Request Parameters

Listen to Notifications​

You can listen to the service changes notification stream or the model changes notification stream.

Request Method

GET

Request URL

https://<host>:<port>/restconf-notification-srv/restconf/notif/notification-stream/hco-notification:{changeType}​

Request Access

permission/hco/restconf-notification-srv:ro

Request Parameters

Retrieve Service Change Events

You can retrieve the events for service-changes.

Request Method

POST

Request URL

https://<host>:<port>/restconf-notification-srv/restconf/operations/hco-notification:get-service-changes -d '{"hco-notification:input": { "service-identifiers": []}}'

Request Access

permission/hco/restconf-notification-srv:ro

Request Body

Retrive Model Change Events

You can retrieve the events for model-changes.

Request Method

POST

Request URL

https://<host>:<port>/restconf-notification-srv/restconf/operations/hco-notification:get-model-changes -d '{"hco-notification:input": { "model-identifiers": []}}'

Request Access

permission/hco/restconf-notification-srv:ro

Request Body

 

Get Data Dump

The get-data-dump endpoint can be used to retrieve all events, with options for from a change-id range and a maximum number of items.

Request Method

POST

Request URL

https://<host>:<port> /restconf-notification-srv/restconf/operations/hco-notification:get-data-dump  -d '{"hco-notification:input": {"from-cursor-id":<string>}}'​ ​

Request Access

permission/hco/restconf-notification-srv:ro

Request Body

 

There is a maximum number of items that the system supports, and exceeding this limit results in an error.

To change the threshold for get-data-dump​, in sedo run the command:

●        sedo config set restconf-notification-srv_maxNumberOfResponseItems_global 1000
 

This assumes that the threshold parameter exists. If not, add it:​

●        sedo config add --ro-access permission/hco/restconf-notification-srv:ro --rw-access permission/hco/restconf-notification-srv:rw --rw-access permission/admin restconf-notification-srv_maxNumberOfResponseItems_global 1000​[LK1] 

PCE

Crosswork Hierarchical Controller provides an API for calculating the path(s) for a Packet E-Line (PCE) service.  You can access the PCE API:

●        https://<host>:<port>/v2/pce/pathRequest

Path Request

Use this API to calculate the specified number of paths for a Packet E-Line service between the source and destination ports. The API optimizes the paths based on the number of hops. Optionally, specify ports and links to exclude from the path. The API body accepts JSON payloads.

Request Method

POST

Request URL

https://<host>:<port>/v2/pce/pathRequest

Request Access

permission/hco/pce:rw

Request Body

Request Body Example

{

  "sourcePort":"PO/eth/IN/ROADM/topogen-ciena-tl1/e6efe0aeafd3c0e4/09c95625a2426f04",

  "destinationPort":"PO/r_physical/IN/Router/topogen-cisco-ios/878d97e102eb161e/0e21dcae3bf2ac56",

  "optimizationGoal":"HOPS",

  "layer":"ETH",

  "numberOfPaths":1

}

Response Example

{

  "topologyTimestampuSec":1723186696183728,

  "optimizationGoal":"HOPS",

  "layer":"ETH",

  "sourceNodeName":"OTN1BOR01",

  "sourcePortGuid":"PO/eth/IN/ROADM/topogen-ciena-tl1/e6efe0aeafd3c0e4/09c95625a2426f04",

  "destinationNodeName":"CR1.LYO",

  "destinationPortGuid":"PO/r_physical/IN/Router/topogen-cisco-ios/878d97e102eb161e/0e21dcae3bf2ac56",

  "paths":[

    {

      "cost":2.0,

      "hopDetails":[

        {

          "nodeGuid":"IN/ROADM/topogen-ciena-tl1/e6efe0aeafd3c0e4",

          "nodeName":"OTN1BOR01",

          "linkGuid":"LI/eth/IN/ROADM/topogen-ciena-tl1/e6efe0aeafd3c0e4/c1a667d20938dea2/IN/ROADM/topogen-ciena-tl1/4af93fac38a5462b/8b66c0bb3f01f6ff",

          "linkName":"OTN1BOR01/2-3-1 to OTN1LYO01/2-2-4",

          "portAGuid":"PO/eth/IN/ROADM/topogen-ciena-tl1/e6efe0aeafd3c0e4/c1a667d20938dea2",

          "portBGuid":"PO/eth/IN/ROADM/topogen-ciena-tl1/4af93fac38a5462b/8b66c0bb3f01f6ff",

          "direction":"A_TO_B",

          "portRate":"100000000000",

          "cost":1.0,

          "hopLatency":0.0

        },

        {

          "nodeGuid":"IN/ROADM/topogen-ciena-tl1/4af93fac38a5462b",

          "nodeName":"OTN1LYO01",

          "linkGuid":"LI/CL/PO/r_physical/IN/Router/topogen-cisco-ios/878d97e102eb161e/295103354226b66c/PO/eth/IN/ROADM/topogen-ciena-tl1/4af93fac38a5462b/13c5483557a96409",

          "linkName":"CR1.LYO/FortyGigE0/0/3/6 to OTN1LYO01/1-6-2",

          "portAGuid":"PO/r_physical/IN/Router/topogen-cisco-ios/878d97e102eb161e/295103354226b66c",

          "portBGuid":"PO/eth/IN/ROADM/topogen-ciena-tl1/4af93fac38a5462b/13c5483557a96409",

          "direction":"A_TO_B",

          "portRate":"0",

          "cost":1.0,

          "hopLatency":0.0

        }

      ]

    }

  ]

}

 

 

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 3.        Inventory Types

Link Types

Table 4.        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 5.        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 6.        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 7.        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 8.        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 9.        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 10.     inventory_item properties

port Properties

Table 11.     port properties

port_to_port Properties

Table 12.     Port_to_port properties

link Properties

Table 13.     link properties

site Properties

Table 14.     site properties

service Properties

Table 15.     service properties

service_intent Properties

Table 16.     service_intent properties

service_intent_domain_op Properties

Table 17.     Service_intent_domain_op properties

service_intent_resource Properties

Table 18.     service_intent_resource Properties

si_domain_op Properties

Table 19.     Service_intent_domain_op properties

event Properties

Table 20.     event properties

srlg Resource Properties

Table 21.     srlg properties

path Properties

Table 22.     path properties

site_link Properties

Table 23.     site_link properties

visual_site Properties

Table 24.     visual_site properties

inventory Properties

Table 25.     inventory properties

srlg_risk_resource_mtm Properties

Table 26.     srlg_risk_resource_mtm properties

risk_resource Properties

Table 27.     risk_resource properties

region Properties

Table 28.     region properties

history Properties

Table 29.     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