The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
Introducing Crosswork Hierarchical Controller APIs
Cisco Crosswork Hierarchical Controller offers an extensive set of APIs as a northbound interface to service orchestrators, OSSs, and Inventory systems. These APIs are essential tools to automate operational workflows, planning scenarios, and administrative tasks. These APIs can be used to retrieve information, provision services and resources, build the network and register for notifications.
Crosswork Hierarchical Controller makes use of multiple technologies for these APIs:
● RESTCONF – based on YANG models defined for NETCONF
● REST with JSON in body
● REST with SHQL in body
API Architecture and Technologies
RESTCONF/YANG Protocol Introduction
The RESTCONF protocol is an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG 1.0 [RFC 6020] or YANG 1.1 [RFC 7950] using the data store concepts defined in the Network Configuration Protocol (NETCONF) [RFC 6241] and further extended in NMDA [RFC 8342].
The main reasons for selecting RESTCONF include:
● The capability of mapping HTTP CRUD operations to provide a model-driven API.
● The ability to use a ubiquitous REST architecture used by many Web applications.
● The ability to use and mix various standard data models defined in the YANG modeling language produced by multiple SDOs. This potentially allows an implementor a choice of SDN architectures, namely IETF ACTN, ONF TAPI, and MEF TAPI.
Crosswork Hierarchical Controller’s RESTCONF implementation consists of the following resources:
● +restconf}/data (Data API): Create/Retrieve/Update/Delete (CRUD) based API for the entire configuration data tree defined in the YANG data models.
● +restconf}/operations (Operations API): RPC-based API entry to trigger RPC defined in YANG.
● +restconf}/data/ietf-restconf-monitoring:restconf-state/streams (Notifications API): RESTCONF API to discover possible Notification streams as defined in RESTCONF protocol. See Device Management for more information.
● +restconf}/yang-library-version: This mandatory leaf identifies the revision date of the "ietf-yang-library" YANG module that is implemented by this server.
As per RFC 8040, the RESTCONF implementation supports JSON encoding for YANG data [RFC 7951]. The server accepts “application/yang-data+json”.
According to the RESTCONF specification, each operation allows zero or more query parameters to be present in the request URI. Specifically, query operations’ parameters are described in Section 4.8 of [RFC 8040]. The following table describes the supported query parameters.
Table 1. Supported Query Parameters
Name |
Methods |
Description |
content |
GET |
Select config and/or non-config data resources |
depth |
GET |
Request limited subtree depth in the reply content |
fields |
GET |
Request a subsect of the target resource content |
Crosswork Hierarchical Controller serves all NBI-accessed data over TLS [RFC 5246] – a transport-layer providing data integrity and confidentiality. Any client accessing Crosswork Hierarchical Controller MUST support TLS 1.2 and above.
Crosswork Hierarchical Controller NBI presents an X.509v3 certificate upon establishing a TLS connection with a client.
A client MUST support certificate validation as per RESTCONF [RFC 8040 Section 2]. The RESTCONF client MUST either (1) use X.509 certificate path validation [RFC5280] to verify the integrity of the RESTCONF server's TLS certificate or (2) match the server's TLS certificate with a certificate obtained by a trusted mechanism (e.g., a pinned certificate). If the X.509 certificate path validation fails and the presented X.509 certificate does not match a certificate obtained by a trusted mechanism, the connection MUST be terminated, as described in Section 7.2.1 of [RFC5246].
NOTE: For the purpose of testing, a client may disable certificate validation to check interface functionality.
Crosswork Hierarchical Controller client authentication is based on HTTP Basic Authentication [RFC 7617]. A client must present a username and password over the established TLS connection. More specifically, a client must use an Authorization header using a Basic authentication scheme. For further information, see the HTTP Authentication Scheme Registry [RFC 7235].
Crosswork Hierarchical Controller supports APIs for receiving notifications, information, and provisioning services.
● Device manager: Various APIs that allow you to manage adapters, devices and credentials
● Get inventory: Get optical devices and routers, their cards, ports, and their attributes.
● Get performance counters: Get L2 performance (throughput) counters per specific port or link.
● Cross links: Various APIs to administer cross links.
● Shared risk: Various APIs that allow you to administer shared risk policies and rules.
● Root Cause Analysis: Various APIs for RCA.
● Generic queries: Use SHQL commands to query any data from the Crosswork Hierarchical Controller model.
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
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
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
Parameter Name |
Data Type |
Description |
adapterGuid |
string |
The adapter guid. Use the guid returned by the Get Adapters method. |
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"
]
}
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
Parameter Name |
Data Type |
Description |
adapterGuid |
string |
The adapter guid. Use the guid returned by the Get Adapters method. |
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"
]
}
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
Parameter Name |
Data Type |
Description |
adapterGuid |
string |
The adapter guid. Use the guid returned by the Get Adapters method. |
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
Parameter Name |
Data Type |
Description |
description |
string |
The device name. |
site |
string |
The site or specify null for no site. |
Request Body Example
{
"name": "router-a",
"site": null
}
Response Example
{
"device_manager_guid": "a2087abe-5753-4387-b372-f8cfb571bb1e"
}
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
Parameter Name |
Data Type |
Description |
deviceGuid |
string |
The device guid. Use the device_manager_guid returned by the Get All Devices method. |
adapterGuid |
string |
The adapter guid. Use the guid returned by the Get Adapters method. |
Request Body
Parameter Name |
Data Type |
Description |
description |
string |
The adapter's device parameters. The schema can be retrieved with the Get Adapter Device Schema API. Ensure that you add the parameters that are marked as required. In this schema example: "required": [ "enabled", "host", "port" ] |
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
Parameter Name |
Data Type |
Description |
deviceGuid |
string |
The device guid. Use the device_manager_guid returned by the Get All Devices method. |
adapterGuid |
string |
The adapter guid. Use the guid returned by the Get Adapters method. |
Request Body
Parameter Name |
Data Type |
Description |
description |
string |
The adapter's device parameters. The schema can be retrieved with the Get Adapter Device Schema API. Ensure that you add the parameters that are marked as required. In this schema example: "required": [ "enabled", "host", "port" ] |
Request Body Example
{
"host": "1.1.1.1",
"port": 22,
"enabled": true
}
Response Example
200 Successful
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
Parameter Name |
Data Type |
Description |
deviceGuid |
string |
The device guid. Use the device_manager_guid returned by the Get All Devices method. |
adapterGuid |
string |
The adapter guid. Use the guid returned by the Get Adapters method. |
Response Example
200 Successful
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
Parameter Name |
Data Type |
Description |
deviceGuid |
string |
The device guid. Use the device_manager_guid returned by the Get All Devices method. |
adapterGuid |
string |
The adapter guid. Use the guid returned by the Get Adapters method. |
Response Example
200 Successful
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
Parameter Name |
Data Type |
Description |
deviceGuid |
string |
The device guid. Use the device_manager_guid returned by the Get All Devices method. |
Request Body
Parameter Name |
Data Type |
Description |
guid |
string |
The site GUID. |
Request Body Example
{
"guid": "ST/e7df76d7a9cb"
}
Response Example
200 Successful operation.
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
Parameter Name |
Data Type |
Description |
deviceGuid |
string |
The device guid. Use the device_manager_guid returned by the Get All Devices method. |
Response Example
{
"adapte-name": {
"last-successfull-discovery": "2020-05-04T17:50:15.530Z"
}
}
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
Parameter Name |
Data Type |
Description |
deviceGuid |
string |
The device guid. Use the device_manager_guid returned by the Get All Devices method. |
Response Example
{
"device_manager_guid": "83ce57e9-a82b-488a-994b-f8c4191f0158",
"inventory_type": null,
"device_model_guid": null,
"name": "router-a",
"adapters": {
"cisco_ios_xr": {
"adapter_guid": "cisco_ios_xr",
"config": {
"host": "1.1.1.2",
"port": 22,
"enabled": false
},
"enabled": false
}
},
"identifiers": {
"host_name": null,
"tid": null,
"serial": null,
"loopback_mac": null,
"loopback_ip": null,
"extra": {}
},
"site": null,
"pending_delete": false,
"enabled": false
}
Remove Device from Crosswork Hierarchical Controller
Use this API to remove the device from Crosswork Hierarchical Controller.
Request Method
DELETE
Request URL
https://<host>:<port>/device-manager-srv/public/rest/device/{deviceGuid}?force=true
Request Access
permission/hco/device-manager-public-api:rw
Request Parameters
Parameter Name |
Data Type |
Description |
deviceGuid |
string |
The device guid. Use the device_manager_guid returned by the Get All Devices method. |
force |
string |
Whether to remove the device from the system even if it is assigned to an adapter. |
Response Example
200 OK!
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
Parameter Name |
Data Type |
Description |
type |
array[string] |
SSH_USER_PASSWORD, SSH_PUBLIC_KEY, HTTP, SNMP_COMMUNITY, SFTP |
Response Example
[
{
"name": "A",
"type": "SSH_USER_PASSWORD"
},
{
"name": "Cisco",
"type": "SSH_USER_PASSWORD"
},
{
"name": "junos",
"type": "SSH_USER_PASSWORD"
}
]
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
Parameter Name |
Data Type |
Description |
name |
string |
The credential name. |
Request Body
Parameter Name |
Data Type |
Description |
type |
array[string] |
SSH_USER_PASSWORD, SSH_PUBLIC_KEY, HTTP, SNMP_COMMUNITY, SFTP |
config |
description |
The credentials parameters structure as described by the Get Credentials API. |
Request Body Example
{
"type": "SSH_USER_PASSWORD",
"config": {}
}
Response Example
201 Successful Operation
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
Parameter Name |
Data Type |
Description |
name |
string |
The credential name. |
Request Body
Parameter Name |
Data Type |
Description |
type |
array[string] |
SSH_USER_PASSWORD, SSH_PUBLIC_KEY, HTTP, SNMP_COMMUNITY, SFTP |
config |
description |
The credentials parameters structure as described by the Get Credentials API. |
Request Body Example
{
"type": "SSH_USER_PASSWORD",
"config": {}
}
Response Example
200 Successful Operation
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
Parameter Name |
Data Type |
Description |
name |
string |
The credential name. |
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
Parameter Name |
Data Type |
Description |
type |
array[string] |
SSH_USER_PASSWORD, SSH_PUBLIC_KEY, HTTP, SNMP_COMMUNITY, SFTP |
Response Example
{
"type": "object",
"properties": {
"username": {
"title": "Username",
"type": "string"
},
"password": {
"title": "Password",
"type": "string",
"encrypted": true
}
},
"required": [
"username",
"password"
]
}
The physical inventory API provides information on optical network elements/devices and their attributes, slots, cards, and ports.
This API supports optical devices only.
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
Parameter Name |
Data Type |
Description |
deviceGuid |
string |
The device guid. |
Query Parameters
Parameter Name |
Data Type |
Description |
full |
boolean (true/false) |
Whether or not to return a detailed device inventory. |
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
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
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.
Interface Type |
Interface Operation |
Request Method |
URI |
Performance |
RPC to retrieve raw performance counters per object type in a time range. |
GET |
/api/v2/timeseries/stats/ |
Performance |
RPC to retrieve raw performance counters per object type in the latest time range. |
GET |
/api/v2/timeseries/stats/latest |
Performance |
RPC to retrieve raw performance counters for specific ports (not one and not ALL the ports) |
PUT |
/api/v2/timeseries/stats/bulkStatsQuery |
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
Parameter Name |
Data Type |
Value |
Description |
objGuid |
string |
|
The object guid. |
pmType |
array[string] |
DELAY_USEC, MIN_RTT_USEC OCTET_OUT |
The PM type. |
streamId |
numeric |
|
The stream ID. |
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
Parameter Name |
Data Type |
Value |
Description |
objGuid |
string |
|
The object guid. |
timestamp |
datetime |
|
The time. |
deviceType |
string |
|
The device type, for example, ROUTER. |
timePeriodSec |
numeric |
|
The time in seconds. |
pmType |
array[string] |
DELAY_USEC, MIN_RTT_USEC OCTET_OUT |
The PM type. |
value |
numeric |
|
The performance statistic. |
streamId |
numeric |
|
The stream ID. |
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
Parameter Name |
Data Type |
Value |
Description |
startTimeStamp |
datetime |
|
The start of the period. |
endTimeStamp |
datetime |
|
The end of the period. |
objGuid |
string |
|
The object guid. |
pmType |
array[string] |
DELAY_USEC, MIN_RTT_USEC OCTET_OUT |
The PM type. |
streamId |
numeric |
|
The stream ID. |
Request Example
GET /api/v2/timeseries/stats?startTimeStamp=1643793190000&
endTimeStamp=1643878292000&pmTypeDELAY_USEC&objGuid= PO/r_logical/16f1596a46b13da5/7d82f458ff24bfa3
Request Parameters
Parameter Name |
Data Type |
Value |
Description |
objGuid |
string |
|
The object guid. |
Timestamp |
datetime |
|
The time. |
deviceType |
string |
|
The device type, for example, ROUTER. |
timePeriodSec |
numeric |
|
The time in seconds. |
pmType |
array[string] |
DELAY_USEC, MIN_RTT_USEC OCTET_OUT |
The PM type. |
Value |
numeric |
|
The performance statistic. |
streamId |
numeric |
|
The stream ID. |
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
Parameter Name |
Data Type |
Description |
startTimeStamp |
datetime |
The start of the period. |
endTimeStamp |
datetime |
The end of the period. |
d@ports.json |
JSON string |
Where ports.json is list of the guids. |
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
Parameter Name |
Data Type |
Value |
Description |
objGuid |
string |
|
The object guid. |
timeStamp |
datetime |
|
The time. |
deviceType |
string |
|
The device type, for example, ROUTER. |
timePeriodSec |
numeric |
|
The time in seconds. |
pmType |
array[string] |
DELAY_USEC, MIN_RTT_USEC, OCTET_OUT |
The PM type. |
value |
numeric |
|
The performance statistic. |
streamId |
numeric |
|
The stream ID. |
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
}
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.
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"
}
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
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
Parameter Name |
Data Type |
Description |
guid |
string |
The cross link guid. Use the guid returned by the Get All Manual Cross Links method. |
Response Example
The response returns the following for the cross link:
● guid: The link guid
● interfaceA – deviceName, interfaceName, type, and guid
● interfaceB – deviceName, interfaceName, type, and guid
● technology (ETH or NMC)
● relatedModelObjectGuid
● additionTimeEpochMillis
● description
● validated: Whether the link has been validated.
● validationResult: The validation result (VALIDATED_BY_PORT_ADJACENCY, VALIDATED_BY_CORRELATION, NOT_CORRELATED, INCONCLUSIVE, UNKNOWN, or CONFLICT).
● lastValidationCheck: The timestamp when the link was last validated.
● lastConflictTime: This timestamp is hidden if there was never a conflict. If this is the same as the lastValidationCheck, then the manual link is currently in conflict. If lastValidationCheck is later than the lastConflictTime, then the manual link was in conflict before but is not in conflict currently. If in addition validated is true, this manual link appears in the network model.
● conflicts: If a link is or was conflicted, the conflicts list is populated with one or two conflicting pairs, one pair per each of the manual-link ports.
{
"guid": "23f6e6c340268f068f817f8f9484aa54a2ba92d5d7072efd7940308f8ecc8fa5",
"interfaceA": {
"deviceName": "CR2.ATH",
"interfaceName": "TenGigE0/0/1/13",
"type": "R_PHYSICAL",
"guid": "PO/r_physical/8ff611ed7ebcd772/2c4e6530608a213d"
},
"interfaceB": {
"deviceName": "SD2ATH02",
"interfaceName": "ETH-1-1-8",
"type": "ETH",
"guid": "PO/eth/ecf4e9a6bbb76cbc/86cdb5c6379e5c62"
},
"technology": "ETH",
"relatedModelObjectGuid": "LI/eth/8ff611ed7ebcd772/2c4e6530608a213d/ecf4e9a6bbb76cbc/86cdb5c6379e5c62",
"additionTimeEpochMillis": 1666695054475,
"description": "cross link description",
"validated": true,
"validationResult": "VALIDATED_BY_PORT_ADJACENCY",
"lastValidationCheck": 1668598747209,
"conflicts": [
{
"a": { "deviceName": "dev-name-of-manual-link-interfaceA", "interfaceName": "iface-name-of-manual-link-interfaceA" },
"b": { "deviceName": "dev-name-of-different-than-manual-link-interfaceB", "interfaceName": "iface-name-different-than-manual-link-interfaceB" }
},
{
"a": { "deviceName": "dev-name-of-manual-link-interfaceB", "interfaceName": "iface-name-of-manual-link-interfaceB" },
"b": { "deviceName": "dev-name-of-different-than-manual-link-interfaceA", "interfaceName": "iface-name-different-than-manual-link-interfaceA" }
}
]
}
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": []
}
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
Parameter Name |
Data Type |
Description |
guid |
string |
The cross link guid. Use the guid returned by the Get All Manual Cross Links method. |
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
Parameter Name |
Data Type |
Description |
interfaceA |
|
Port A |
deviceName |
string |
The device name. |
interfaceName |
string |
The interface name. |
interfaceB |
|
Port B |
deviceName |
string |
The device name. |
interfaceName |
string |
The interface name. |
technology |
string |
The technology. |
Description |
string |
The description. |
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"}
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
Parameter Name |
Data Type |
Description |
guid |
string |
The cross link guid. Use the guid returned by the Get All Manual Cross Links method. |
Response Example
200 OK
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
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\"]"
]
}
]
}
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
Parameter Name |
Data Type |
Description |
policyGuid |
string |
The policy guid. Use the guid returned by the Get Policies method. |
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\"]"
]
}
]
}
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
Parameter Name |
Data Type |
Description |
policyGuid |
string |
The policy guid. Use the guid returned by the Get Policies method. |
Request Body
Parameter Name |
Data Type |
Description |
shared_risk_types |
string |
Link, Port, Card, Shelf, Device |
policy_type |
string |
SINGLE-PROTECTED or MULTIPLE-LINKS. |
Request Body Example
{
"shared_risk_types": [
"Link"
],
"policy_type": "SINGLE-PROTECTED"
Response Example
201 Successful Operation
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
Parameter Name |
Data Type |
Description |
policyGuid |
string |
The policy guid. Use the guid returned by the Get Policies method. |
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
Parameter Name |
Data Type |
Description |
policyGuid |
string |
The policy guid. Use the guid returned by the Get Policies method. |
Request Body
Parameter Name |
Data Type |
Description |
shared_risk_types |
string |
Link, Port, Card, Shelf, Device |
Request Body Example
{
"shared_risk_types": [
"Link"
]
}
Response Example
200 Successful Operation
Use this API to update credentials.
Request Method
PUT
Request URL
https://<host>:<port>/srlg-app/public/rest/policy/{policyGuid}/policy-type
Request Access
permission/hco/user
Request Parameters
Parameter Name |
Data Type |
Description |
policyGuid |
string |
The policy guid. Use the guid returned by the Get Policies method. |
Request Body
Parameter Name |
Data Type |
Description |
policy_type |
string |
SINGLE-PROTECTED or MULTIPLE-LINKS. |
Request Body Example
{
"policy_type": "SINGLE-PROTECTED"
}
Response Example
200 Successful Operation
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
Parameter Name |
Data Type |
Description |
policyGuid |
string |
The policy guid. Use the guid returned by the Get Policies method. |
ruleName |
string |
The rule name. Use one of the rule names returned by the Get Policies method. |
Request Body
Parameter Name |
Data Type |
Description |
resources |
array(string) |
A list of GUID links and/or an SHQL query. If you use an SQHL query, make sure that the expression is valid and returns a result. See the SQHL User Guide. When you pass an SQHL query, ensure that you wrap "…." with a pair of \s, for example: "link[.layer=\"R_LOGICAL\"]" |
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
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
Parameter Name |
Data Type |
Description |
policyGuid |
string |
The policy guid. Use the guid returned by the Get Policies method. |
ruleName |
string |
The rule name. Use one of the rule names returned by the Get Policies method. |
Request Body
Parameter Name |
Data Type |
Description |
resources |
array(string) |
A list of GUID links and/or an SHQL query. If you use an SQHL query, make sure that the expression is valid and returns a result. See the SQHL User Guide. When you pass an SQHL query, ensure that you wrap "…." with a pair of \s, for example: "link[.layer=\"R_LOGICAL\"]" |
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
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
Parameter Name |
Data Type |
Description |
policyGuid |
string |
The policy guid. Use the guid returned by the Get Policies method. |
ruleName |
string |
The rule name. Use one of the rule names returned by the Get Policies method. |
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 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
Parameter Name |
Data Type |
Description |
link_guid |
string |
The link guid. Use the guid returned by the GET RCA on All Links method. |
Response Example
{
"affected_services": [],
"affected_links": [
{
"name": "SR_P_600_reverse",
"guid": "LI/sr_policy/igp/isis/default-domain/CR1.DUB/l2/router-id/100.0.0.1:igp/isis/default-domain/CR1.SPB/l2/router-id/100.0.0.123/14601"
}
],
"affected_services_num": 0,
"affected_links_num": 1
}
Generic Information Retrieval using SHQL
Crosswork Hierarchical Controller provides a specialized query language designed for network data, called Sedona Hierarchical Query Language (SHQL). SHQL allows users to specify any query and quickly see the results, as well as to save the query for the benefit of others.
SHQL is unique in the way that it allows users to query a multi-layer model using simple keywords. Keywords allow for navigating the model, transitioning from one object type to another, and eliminating the need for complex conditions.
Transitioning is when SHQL allows for retrieving a list of objects and using this to transition to related objects, for example, retrieve all the SITES in the system and then use a language operator “|” (pipe operator) to get all INVENTORY in those sites etc.
For example, all OMSs used by a specific LSP can be retrieved using just a ‘downward’ command that retrieves, for the specified LSP, all links in the specified lower layer.
link[.name="my_lsp"] | downward ("OMS")
SHQL can be used in the UI application in Crosswork Hierarchical Controller or as REST POST commands.
POST
https://<server>/api/v2/shql
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"]
{
"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
}
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.
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
Description |
|
Optical Node |
An optical network element that is actively managed. This can be an amplifier, ROADM, transponder, or muxponder. |
Router |
A distinct instance of a router that has a loopback IP address and physical inventory. |
IGP Inventory Item |
A logical/virtual router as an instance in router. |
Power Supply |
A power supply module in an optical node or router. |
Card |
Any type of pluggable card. |
Shelf |
A chassis of a router or optical node. |
Fan Tray |
A pluggable or manageable fan tray unit in an optical node or router. |
Inventory |
Description |
Fiber Segment |
A physical fiber line that spans from one DUCT to another and is used as a segment in a fiber link. |
Fiber |
A chain of fiber segments that spans from one optical device to another. |
OTS |
The logical layer used as an underlay for the OMS link. One OTS link can be created over a fiber link. |
OMS |
The logical layer used as an underlay for the OCH link. One OMS link can be created over a chain of OTS links. |
NMC |
A wavelength connection between two ROADMs over one or more OMS links, not connecting to client ports on muxponder. |
OCH |
A wavelength connection spanning the client port of one OEO device (transponder, muxponder, regenerator) and another. 40 or 80 OCH links can be created on top of an OMS link. An OCH link spans from one client port to another, where the client port is either a TDM or ETH port. |
SCH |
An OCH that spans from one ROADM device to another and terminates in a device and not in a client port. |
STS, OCG, OC |
The TDM links that span from one optical device to another, ride on top of OCH links and terminate in TDM client ports |
OTU |
The underlay link in the OTN layer, used for ODU links. It can ride on top of an OCH. |
ODU |
The sub signals in OTU links. Each OTU link can carry multiple ODU links, and ODU links can be divided into finer granularity ODU links recursively. |
ETH Link |
An ETH L2 link, that spans from one ETH UNI port to another, and rides on top of an ODU link. |
ETH Chain |
A chain of ETH links. |
L3 Physical |
An ethernet link (L2 connectivity) between two ETH ports. This is the underlay layer for an IP subnet link between two routers. |
Agg |
The Link Aggregation Group (LAG) where multiple ETH links are grouped to create higher BW and a resilient link. |
Logical Link |
A link where two IP subnets are connected over a physical link between two routers. |
IGP |
The path calculated by the router as the shortest path between two specific nodes. The link between two routers that carries IGP protocol messages. The link represents an IGP adjacency. |
Tunnel |
The MPLS RSVP, or Segment Routing tunnel created between two routers over IGP links, with or without TE options. |
L3-VPN Link |
The connection between two sites of a specific L3-VPN (can be a chain of LSP connections or an IGP path). |
Crosswork Hierarchical Controller Connection Model
For example: 10GE over 100G OTN link
Connection Model
This example finds if there are shared OMSs between two LSPs.
SHQL Example
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).
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
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.
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.
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.
Figure 14.
Saved Queries
3. Repeat steps 1 and 2 for every query you want to save.
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.
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
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([ ]).
Operand |
Numerical |
String |
Description |
!= |
✓ |
✓ |
Different than. |
< |
✓ |
|
Less than. |
<= |
✓ |
|
Less than or equal to. |
= |
✓ |
✓ |
Equal to. |
> |
✓ |
|
Larger than. |
>= |
✓ |
|
Larger than or equal to. |
contains |
|
✓ |
Partial match. |
endswith |
|
✓ |
Ending with a given pattern. |
has |
|
|
Item in an array. Use to look for an item when the field is a list. |
in |
✓ |
✓ |
Matched list of patterns. Use when the field is a single item and the filter contains multiple items. |
intersect |
✓ |
|
Geographical intersection of regions at a specific longitude and latitude. For example: region[.geometry intersect (4.8945398, 52.3666)] |
is |
|
✓ |
Boolean (true / false) and null. |
not |
|
✓ |
Together with is, contains, endswith, startswith, to negate the condition. |
startswith |
|
✓ |
Starting with a given pattern. |
xin |
✓ |
✓ |
Matched lists of patterns for multiple properties. |
~ |
|
✓ |
String with a regular expression. |
Example 1: Filtering with Operands
Figure 20. retrieves a list of routers with names that begin with CR1.
Filtering Using Operand
Figure 21 shows the results.
Query Results
Example 2: Filtering with Operands
Figure 22 retrieves the inventory where the vendor is Ciena.
Filtering Using Operand
Figure 23 shows the results.
Query Results
Example 3: Filtering with Operands
Figure 24 looks for links where (port_a.guid = "PO/igp/06c0868cc5601e85/06c0868cc5601e85" and port_b.guid ="PO/igp/c3b0dc2cd3ad6406/c3b0dc2cd3ad6406") or (port_a.guid = "PO/igp/c3b0dc2cd3ad6406/c3b0dc2cd3ad6406" and port_b.guid = "PO/igp/06c0868cc5601e85/06c0868cc5601e85").
Filtering Using Operand
Figure 25 shows the results.
Query Results
Example 4: Filtering with Operands
Figure 26 retrieves and adds up the events captured the day before yesterday (>-2d and <-1d). The .timeStamp property can be used with d (days), h (hours), m (months), M (minutes). S (seconds), y (years) or w (weeks).
Filtering Using Operand
Figure 27 shows the results.
Query Results
Transforming/Collecting Object Types
You can add an object type to the query command and determine if the data to be retrieved is transformed from one object type to another object type, or if the data reflects a collection of multiple object types and their related items.
● Transformation: Add a pipe (|) to the query command before adding the new object type. Transforms the results relating to the previous object type to output for the new object type.
● Collection: Add an ampersand (&) to the query command before adding the new object type. Retrieves all the output for all the preceding object types.
● As: Add a temporary variable. Enables you to create a query with an object type that is not related to the preceding object type.
The table describes object types and the object types to which they are directly related.
Table 5. Object Types and Properties
Object type |
Object type properties |
event |
history |
inventory |
history inventory_item port service_intent_resource site srlg |
inventory_item |
history inventory_item port service_intent_resource site srlg |
link |
history link path port region service_intent_resource site link srlg |
path |
history path link |
port |
history inventory_item inventory link port port_to_port service service_intent_resource srlg |
port_to_port |
port |
region |
history link site visual_site |
risk_resource |
history inventory_item link port srlg_risk_resource_mtm |
service |
history port service service_intent service_intent_resource |
service_intent |
history service service_intent service_intent_domain_op service_intent_resouces |
service_intent_domain_op |
service_intent |
service_intent_resource |
history inventory_link link port service service_intent service_intent_resouces |
site |
history inventory_item region site visual site |
site_link |
history link site_link visual_site |
srlg |
history inventory_item link port srlg |
srlg_risk_resource_mtm |
history inventory_item link port srlg_risk_resource_mtm |
visual_site |
history region site site_link visual_site |
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
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
Function |
Description |
downward |
Retrieves items from below the layer of the specified item |
upward |
Retrieves items from above the layer of the specified item |
span |
Retrieves items from below and above the layer of the specified item |
fts |
Free text search. Retrieves items according to the search string you enter. |
group_by |
Returns query results grouped by property, for example, how many ports have an OperStatus of Up. |
retrospective(@) |
Retrieves items from the past according to a given timestamp. |
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
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
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).
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
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 (|).
Function |
Description |
add_counters |
Displays the total number per attribute value for the specified object type. |
after (GUID) |
Displays only the results that follow the item with the specified GUID. |
asc (column) |
Displays results in ascending natural order |
desc (column) |
Displays results in descending natural order |
group_by |
|
limit(#) |
Limits the number of displayed results |
view |
Displays the specified properties (with the labels provided) for the query results. |
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
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
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
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
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
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
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
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
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
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
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 and create your own complex query.
Figure 69 shows an example that includes:
● Operands
● Transformations
● Collections
● Functions
Complex Query
Table 8. Breakdown of Complex Query
Item |
Type |
See... |
site |
Object type |
Object Types and Properties |
[.guid = "ST/31105c202abd"] | |
Condition (operand =) |
Operands |
downward |
Function |
SHQL Functions |
| inventory_item |
Transformation object typ |
Transforming/Collecting Object Types |
| port |
Transformation object type |
Transforming/Collecting Object Types |
| link | |
Transformation object type |
Transforming/Collecting Object Types |
upward |
Function |
SHQL Functions |
| link[.layer in ("LSP", "E_LINE")] | |
Transformation object type + condition (operand in) |
Transforming/Collecting Object Types |
limit(20) |
Function |
Output Functions |
& port & inventory_item & site| |
Collections of object types |
Transforming/Collecting Object Types |
upward |
Function |
SHQL Functions |
Figure 70 shows the results.
Complex Query Results
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.
The following sections list all the properties aligned with the different object types.
Note: The alarm object is for use in future versions.
Table 9. inventory_item properties
inventory_item properties |
.accessIdentifier |
.cardStatus |
.cardType |
.children |
.childrenPorts |
.desc |
.deviceFamily |
.deviceType |
.domainName |
.equipState |
.extra |
.formFactor |
.guid |
.hasRoadm |
.id |
igpType |
.isisInfo |
.isisInfo.areaAddresses |
.isisInfo.instanceIdentifier |
.isisInfo.isDiscoveredL1 |
.isisInfo.isDiscoveredL2 |
.isisInfo.systemId |
.isisInfo.topologyIdentifier |
.managementIp |
.modelNumber |
.name |
.oui |
.parent |
.partNumber |
.pluggability |
.provider |
.reachabilityStatus |
.routerId |
.serialNumber |
.site |
.softwareVersion |
.supportedLambdas |
.supportedPhysicalLayers |
.supportedReacabilityMeters |
.supportedSpeeds |
.tags |
.topologyId |
.tunableType |
.tunedLambda |
.type |
.unitType |
.vendor |
Table 10. port properties
port properties |
.activeTransmissionParams |
.adjaceny |
.adminGroups |
.adminGroups.groupNumber |
.adminGroups.name |
.adminStatus |
.aggRateBps |
.channelNum |
.childRole |
.containingService |
.desc |
.device |
.egressBandwidthProfile |
.egressBandwidthProfile.cbsKb |
.egressBandwidthProfile.cir |
.egressBandwidthProfile.ebsKb |
.egressBandwidthProfile.eir |
.egressBandwidthProfile.qosPolicy |
.elineSpecific |
.ethPortType |
.exportRts |
.extra |
.guid |
.hasProtection1Plus1Capability |
.hasServiceEndPointCapability |
.id |
.ifIndex |
.igpInstanceName |
.igpMetric |
.importRts |
.ingressBandwidthProfile |
.ingressBandwidthProfile.cbsKb |
.ingressBandwidthProfile.cir |
.ingressBandwidthProfile.ebsKb |
.ingressBandwidthProfile.eir |
.ingressBandwidthProfile.qosPolicy |
.ipAddress |
.isAllToOneBundling |
.isLoopback |
.isManagement |
.isRouterId |
.isStatsDummy |
.isisInfo |
.isisInfo.isisLevel |
.isisInfo.netPrefixMetric |
.isisInfo.portType |
.l2VpnSpecific |
.l3VpnSpecific |
.lambdaNm |
.links |
.lowerPorts |
.mappedCeTags |
.mappedSvlan |
mappingType |
.maxLinkBandwidth |
.maxReservableLinkBandwidth |
.mediaFrameType |
.memberCount |
.mtuSize |
.name |
.nonPrimaryIps |
.ocType |
.oduId |
.oduPolarization |
.oduType |
.operStatus |
ospfInfo |
.otuType |
.packetOpticalDetails |
.packetOpticalDetails.availableBandwidth |
.parent |
.pdhType |
.physicalAddress |
.portCapibilities |
.primaryIp |
.protectionType |
.provider |
.range |
.rfParams |
.routeDistinguisher |
.rsvpReservedBandwidthBps |
.rsvpStaticBandwidthBps |
.spanLoss |
.speedBps |
.srPrefixSids |
.srlgs |
.stmType |
.stsType |
.supportedCapacities |
.supportedSpectrums |
.supportedTransmissionParams |
.tags |
.teMetric |
.transmitPowerDbm |
.type |
.unreservedLinkBwForPriorityIndex |
.unreservedLinkBwForPriorityIndex |
.upperPorts |
.vcatStsType |
.vlan |
.vpnRole |
.vrfName |
.vtTye |
.ycableType |
.zrType |
Table 11. Port_to_port properties
history properties |
.extra |
.guid |
.id |
.portA |
.portB |
.provider |
.type |
link Properties
Table 12. link properties
link properties |
.activeProtectionPriority |
.adjacencySegmentInfo |
.adminGroupConstraints |
.bindingSid |
.candidatePaths |
.color |
.deploymentType |
.desc |
.distanceMeters |
.ecmpLayer |
.evcPerformanceProfile |
.evpnInstance |
.extra |
.geometry |
.guid |
.holdPriority |
.id |
.inverseLinkId |
.isApproximated |
.isBidi |
.isCeVlanCosPreservation |
.isFallbackEnabledAtoB |
.isFallbackEnabledBtoA |
.isUntaggedAllowed |
.latencyMicros |
.layer |
.lineType |
.lspTechnology |
.mappedVlanRange |
.mappingStatus |
.name |
.numberOfFibers |
.operStatus |
.owner |
.pathGroupType |
.paths |
.portA |
.portB |
.prefixSegmentInfo |
.protectedLayer |
.protectionStatus |
.provider |
.role |
.rxLabel |
.segmentType |
.setupPriority |
.sidIndex |
.sidLabel |
.signalType |
.speedBps |
.srAdjacencySids |
.srlgs |
.tags |
.teMetric |
.txLabel |
.usedByHops |
.vcId |
Table 13. site properties
site properties |
.extra |
.guid |
.id |
.latitude |
.longitude |
.name |
.parent |
Table 14. service properties
service properties |
.adminStatus |
.anyToAnyOrHubRouteTarget |
.containedPorts |
.customerDetails |
.customerName |
.deploymentState |
.desc |
.extra |
.guid |
.id |
.isProtectionDegraded |
.name |
.operStatus |
.parent |
.provider |
.serviceHealth |
.serviceIntent |
.serviceIntentRelation |
.signallingType |
.spokeRouteTarget |
.tags |
.type |
.vpnTopology |
.vpnType |
.wavelengthServiceType |
Table 15. service_intent properties
service_intent properties |
.adminState |
.anyToAnyDetails |
.anyToAnyDetails.minimumSites |
.anyToAnyDetails.routeTarget |
.baseTemplate |
.capacity |
.controlMethod |
.customerName |
.dataForNonMultiplexedService |
.dataForNonMultiplexedService.ethPortType |
.deploymentGoal |
.desc |
.extra |
.guid |
.holdPriority |
.hubAndSpokeDetails |
.hubAndSpokeDetails.hubRouteTarget |
.hubAndSpokeDetails.minimumHubSites |
.hubAndSpokeDetails.minimumSpokeSites |
.hubAndSpokeDetails.spokeRouteTarget |
.id |
.intentCreationTime |
.intentModificationTime |
.ipAddressAllocationPolicy |
.ipMplsPseudoWireControlPlane |
.isAggregateLinks |
.isOamPmCollectionEnabled |
.isReadOnly |
.isRemoved |
.isTemplate |
.name |
.nmcSelectedSpectrum |
.ochLambdaNm |
.ochTransmissionParams |
.oduType |
.parent |
.pathComputationProvider |
.pathComputationSettings |
.pathComputationSettings.backupPathOptimization |
.pathComputationSettings.includeLinkStates |
.pathComputationSettings.mainPathOptimization |
.protectionSettings |
.protectionSettings.protectionPolicy |
.protectionSettings.resourceDiversityFor1Plus1 |
.protectionSettings.resourceDiversityFor1Plus1.diversedResources |
.protectionSettings.resourceDiversityFor1Plus1.diversityPolicy |
.provider |
.qosSettings |
.qosSettings.cbsKb |
.qosSettings.cir |
.qosSettings.ebsKb |
.qosSettings.eir |
.qosSettings.qosPolicy |
.relatedServices |
.reservedBandwidth |
.resourceAllocationPolicy |
.resources |
.routeDistinguisher |
.setupPriority |
.srData |
.stmType |
.tePlusPlusData |
.tunnelType |
.type |
.underlayTech |
.underlayTech.allowedNni |
.underlayTech.ipMpls |
.underlayTech.ipMpls.allowedNni |
.underlayTech.ipMpls.tunnelResilliency |
.underlayTech.ipMpls.tunnelTypes |
.underlayTech.mplsTp |
.underlayTech.mplsTp.allowedNni |
.underlayTech.mplsTp.tunnelResilliency |
.underlayTech.mplsTp.tunnelUsageConstraints |
.underlayTech.otn |
.underlayTech.otn.allowedNni |
.underlayTech.otn.serviceTunnelRate |
.underlayTech.otn.serviceTunnelType |
.underlayTech.selectedTech |
.underlayTech.tunnelResilliency |
.underlayTech.tunnelTypes |
.underlayTech.wdm |
.underlayTech.wdm.allowedNni |
.vlanManipulation |
.vpnTopology |
.wavelengthServiceType |
.zrpSpecific |
service_intent_domain_op Properties
Table 16. Service_intent_domain_op properties
history properties |
.domainProvider |
.domainType |
.extra |
.guid |
.id |
.serviceIntent |
service_intent_resource Properties
Table 17. service_intent_resource Properties
service_intent_resource properties |
.constraintCompliance |
.direction |
.endPointAResourceGuid |
.endPointBResourceGuid |
.extra |
.guid |
.id |
.includeType |
.isBidi |
.label |
.layer0Info |
.layer0Info.lambdaNm |
.layer0Info.modulation |
.layer0Info.transmitPowerDbm |
.layer1Info |
.layer1Info.tunnelRate |
.layer2Info |
.layer2Info.attachmentCircuitId |
.layer2Info.ethernetSegmentId |
.layer2Info.mappedCeTags |
.layer2Info.mtuSize |
.layer2Info.qos |
.layer2Info.qos.cbsKb |
.layer2Info.qos.cir |
.layer2Info.qos.ebsKb |
.layer2Info.qos.eir |
.layer2Info.qos.qosPolicy |
.layer3Info |
.layer3Info.cePeSettings |
.layer3Info.cePeSettings.bgpRoutingDetails |
.layer3Info.cePeSettings.bgpRoutingDetails.autonomousSystem |
.layer3Info.cePeSettings.bgpRoutingDetails.peeringIp |
.layer3Info.cePeSettings.ospfRoutingDetails |
.layer3Info.cePeSettings.ospfRoutingDetails.metric |
.layer3Info.cePeSettings.ospfRoutingDetails.ospfArea |
.layer3Info.cePeSettings.routingMethod |
.layer3Info.cePeSettings.staticRoutingDetails |
.layer3Info.cePeSettings.staticRoutingDetails.entries.adminPreference |
.layer3Info.cePeSettings.staticRoutingDetails.entries.ipPrefix |
.layer3Info.cePeSettings.staticRoutingDetails.entries.nextHop |
.layer3Info.ipAddress |
.layer3Info.l3VpnRole |
.order |
.pathResourceGuid |
.preference |
.protectionRole |
.resource |
.resourceDiversity |
.serviceIntent |
.tag |
.type |
Table 18. Service_intent_domain_op properties
history properties |
.domainProvider |
.domainType |
.extra |
.guid |
.id |
.serviceIntent |
event Properties
Table 19. event properties
event properties |
.count |
.data |
.guid |
.lastUpdate |
.machineId |
.severity |
.subType |
.timeStamp |
.type |
.username |
Table 20. srlg properties
srlg properties |
.externalId |
.extra |
.guid |
.id |
.name |
.ordinal |
.provider |
.srlgs |
Table 21. path properties
path properties |
.ecmpWeight |
.extra |
.guid |
.hops |
.id |
.isActive |
.isValid |
.link |
.priority |
.provider |
.srPathSegments |
.tunPortA |
.tunPortB |
Table 22. site_link properties
site_link properties |
.depth |
.guid |
.id |
.isCrossLink |
.layer |
.links |
.name |
.siteA |
.siteB |
.status |
.tags |
.utilization |
Table 23. visual_site properties
visual_site properties |
.depth |
.deviceTypes |
.guid |
.id |
.isOnlyAmplifiers |
.latitude |
.longitude |
.name |
.parent |
.reachabilityStatus |
.routerSize |
.site |
.tags |
Table 24. inventory properties
inventory properties |
.accessIdentifier |
.cardStatus |
.cardType |
.children |
.childrenPorts |
.desc |
.deviceFamily |
.deviceType |
.domainName |
.equipState |
.extra |
.formFactor |
.guid |
.hasRoadm |
.id |
.igpType |
.isisInfo |
.isisInfo.areaAddresses |
.isisInfo.instanceIdentifier |
.isisInfo.isDiscoveredL1 |
.isisInfo.isDiscoveredL2 |
.isisInfo.isisInstanceName |
.isisInfo.systemId |
.isisInfo.topologyIdentifier |
.managementIp |
.modelNumber |
.name |
.oui |
.parent |
.partNumber |
.pluggability |
.ports |
.provider |
.reachabilityStatus |
.routerId |
.serialNumber |
.site |
.softwareVersion |
.srCapabilities |
.srlgs |
.supportedLambdas |
.supportedPhysicalLayers |
.supportedReacabilityMeters |
.supportedSpeeds |
.tags |
.topologyId |
.tunableType |
.tunedLambda |
.type |
.unitType |
.vendor |
srlg_risk_resource_mtm Properties
Table 25. srlg_risk_resource_mtm properties
srlg_risk_resource_mtm properties |
.guid |
.id |
.inventoryItem |
.link |
.port |
.provider |
.srlg |
Table 26. risk_resource properties
risk_resource properties |
.guid |
.id |
.inventoryItem |
.link |
.port |
.provider |
.srlg |
Table 27. region properties
region properties |
.geometry |
.guid |
.id |
.name |
.overlay |
Table 28. history properties
history properties |
.action |
.changes |
.objGuid |
.objName |
.objSubtype |
.objType |
.timestamp |
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.
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.
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
Term |
Description |
RESTCONF |
A protocol based on HTTP for configuring data defined in YANG version 1 or YANG version 1.1 using the datastore concepts defined in the Network Configuration Protocol (NETCONF) |