This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
Americas Headquarters Cisco Systems, Inc. 170 West Tasman Drive San Jose, CA 95134-1706 USA http://www.cisco.com Tel: 408 526-4000 800 553-NETS (6387) Fax: 408 527-0883
Physical Inventory YANG Containment Hirarchy................................................................ 80 6.1Physical Inventory YANG Containment Hierarchy - High Level Class Diagram .................................................. 80 Physical Inventory YANG Containment Hierarchy – Detailed Class Diagram ..................................................... 80
This guide provides information about the RESTCONF/YANG based NBI Northbound APIs supported by Cisco Evolved Programmable Network (EPN) Manager. OSS operators can use this document to integrate Cisco EPN Manager with their OSS system.
Conventions 1.1
This document uses the following conventions:
Convention Indication
bold font Commands and keywords and user-entered text appear in bold font.
italic font Document titles, new or emphasized terms, and arguments for which you supply values are in italic font.
[] Elements in square brackets are optional.
{x|y|z} Required alternative keywords are grouped in braces and separated by vertical bars.
[x|y|z] Optional alternative keywords are grouped in brackets and separated by vertical bars.
String A nonsuited set of characters. Do not use quotation marks around the string or the string will include the quotation marks.
courier
font
For code snippets and XML.
<> Nonprinting characters such as passwords are in angle brackets.
[ ] Default responses to system prompts are in square brackets.
!,# An exclamation point (!) or a pound sign (#) at the beginning of a line of code indicates a comment line.
Note Notes contain helpful suggestions or references to material not covered in the publication.
Obtaining Documentation, Obtaining Support, and Security Guidelines 1.2
For information on obtaining documentation, submitting a service request, and gathering additional information, see the monthly What’s New in Cisco Product Documentation which lists of all the new and revised Cisco technical documentation (http://www.cisco.com/en/US/docs/general/whatsnew/whatsnew.html). Subscribe to the What’s New in Cisco Product Documentation as a Really Simple Syndication (RSS) feed and set content to be delivered directly to your desktop using a
Cisco EPN Manager implements the RESTCONF/YANG API as a standards-based Northbound Interface for integrating Cisco EPN Manager with a standards-compliant OSS. It is a set of RESTFul services confirmed to the RESTCONF/YANG specification.
The Cisco EPN Manager implementation of the RESTCONF/YANG interface supports the retrieval of device inventory, circuit inventory, notifications about respective resource changes, and provisioning which includes Managed Elements and Equipment Inventory.
Web Services Standards 2.1
The RESTCONF implementation of the Cisco EPN Manager is based on the following Web Services specification from W3C standards, as mentioned in the RESTCONF/YANG specification:
YANG – A Data Modeling Language for the Network Configuration Protocol (NETCONF) – RFC-6020
Hypertext Transfer Protocol HTTP 1.1 - RFCs 7230-7237
RESTCONF Standards 2.2
The Cisco EPN Manager implementation of the RESTCONF/YANG Interface exposes EPN-M management information as specified by the RESTCONF/YANG protocol and data modeling language. While no standard exists for information model exposed by this interface, the model is based on TeleManagement Forum (TMF) standards governing the modeling of physical and service inventory.
Communication Patterns 2.3
RESTCONF/YANG interfaces supported by Cisco EPN Manager use REST (Representational State Transfer) techniques. REST is stateless and uses a client-server protocol (HTTP 1.1). The client issues HTTP GET requests to retrieve objects using the URLs and query parameters described in this document.
Containment Associations
The operations on supported RESTCONF/YANG interfaces return a single object or multiple objects, depending how many objects match the URL and whether the object supports
containment associates. For example, when the client retrieves a managed element object, the associated chassis, equipment, models, and physical connectors are returned as well. Such requests can return large amounts of data in response to a single GET request.
OSS Integration Usage Scenarios 2.4
In a typical scenario, OSS clients integrating with Cisco EPN Manager may use the RESTCONF/YANG Interfaces supported by Cisco EPN Manager to retrieve the device inventory and then export the inventory to other systems or use it to generate reports.
Retrieving Inventory
The RESTCONF/YANG interface supports standard HTTP 1.1 GET requests. The information is returned in the format specified by the accept header of the request. The client may retrieve the physical information about a device through the Physical Inventory API. Logical resource and service information are available through the other APIs.
The following table lists the endpoint URLs that can be used to access the supported RESTCONF/YANG Web Services in Cisco EPN Manager: RESTCONF/YANG Web Service Endpoint URL Description
getInterfaceProtocolEndpoint by id Note: Do not use braces for the <id>
Authentication
The RESTCONF/YANG endpoints in Cisco EPN Manager are secured. To access these endpoints, use HTTP basic authentication.
Authorization
User credentials passed for accessing the RESTCONF/YANG endpoints require the proper authorization to use the API. This authorization can be configured using Cisco EPN Manager security management interface. In Cisco EPN Manager, NBI Read privileges are required to access all retrieval RESTCONF/YANG interfaces, and NBI Write privileges are required to use the provisioning RESTCONF/YANG interface.
License
A Cisco EPN Manager RESTCONF/YANG license is required to use RESTCONF/YANG interface endpoints.
This section provides details about the supported RESTCONF/YANG interfaces.
Group Retrieval 4.1
This interface provides the operations to retrieve Group entities. This object represent automatic and user defined groups to which ManagedElements may belong.
Group Data
Associated objects are represented by a collection, for one-to-many associations, or an attribute of the object type for one-to-one or many-to-one associates. The role of the object(s) in the association provides the name for association attributes. The API traverses selected associations, usually of one-to-many cardinality, to allow retrieval of a hierarchy of objects in a single request. Attribute names of such associations are followed by an asterisk (*). To prevent cycles in the retrieval or divide the hierarchy into manageable pieces, other associations are summarized as a string with an entry giving the object type, name, and business key for each object in the collection. Some attributes may not be displayed since null values and empty associations are not included in the response. The following table lists the attributes in the Group object: Group Data Data Type Description
instanceId int Instance identifier of entity in the database.
description String Description of the group.
name String Name of the group.
managedElements Set<ManagedElement> ManagedElements within the group.
Operations
The following table lists the operations available to retrieve Group data from RESTCONF via the http protocol:
This interface provides the operations to retrieve ManagedElement entities. This object represents a device managed by Cisco EPN Manager.
ManagedElement Data
The table below lists the attributes in the ManagedElement object. Associated objects are represented by a collection, for one-to-many associations, or an attribute of the object type for one-to-one or many-to-one associates. The role of the object(s) in the association provides the name for association attributes. The API traverses selected associations, usually of one-to-many cardinality, to allow retrieval of a hierarchy of objects in a single request. Attribute names of such associations are followed by an asterisk (*). To prevent cycles in the retrieval or divide the hierarchy into manageable pieces, other associations are summarized as a string with an entry giving the object type, name, and business key for each object in the collection. Some attributes may not be displayed since null values and empty associations are not included in the response.
ManagedElement Data Data Type Description instanceId int Instance identifier of entity in the database.
businessKey String String representation of attribute value(s) that uniquely identify the entity or instanceId if no business key defined.
clusterCount int Cluster count.
collectionStatus String A detailed status of inventory collection - Success or failure.
collectionTime datetime Collection time.
communicationState CommunicationStateEnum
Indicates management availability or reachability of the managed network element. It can indicate the availability or reachability of the management agent serving as a proxy for the network element.
creationTime datetime Creation time.
description String Description of the MNE.
fdn String The fully qualified domain name (FDN) for the equipment (or equipment subclass) instance.
lastBootTime datetime Represents the time the management agent on the
lifecycleState LifecycleStateEnum Represents the current management state of the network element: managed, unmanaged, under maintenance, and so on. This state is modified by events in the network and network management system, and also by user request.
managementAddress String The ip address of the device. This is the preferred management access address for the device. This is typically an address at which SNMP, telnet, and ssh agents are available.
name String The name of the MNE.
owningEntityId String Entity ID
productFamily String The contents of the NAME attribute of the outer-most <DEVICEGROUP> element in a Cisco MDF file for this particular instance of ManagedNetworkElement.
productSeries String The contents of the NAME attribute of the second-level <DEVICEGROUP> element in a Cisco MDF file for this particular instance of ManagedNetworkElement.
productType String The contents of the NAME attribute of the <DEVICE> element in a Cisco MDF file for this particular instance of ManagedNetworkElement.
productVendor String product vendor
satelliteCount int Number of satellites.
softwareFamily String software Family
softwareType String A string that identifies the specific type of software that is installed on this ManagedNetworkElement. For example, Cisco IOS or Linux.
softwareVersion String The specific version of the software (see attribute softwareType) that is installed. The value is formatted as a text field.
sysContact String sysContat of the mne
sysLocation String The physical location of this node (for example, 'telephone closet, 3rd floor'). If the location is unknown, the value is the zero-length string.
sysObjectId String The vendor's authoritative identification of the network management subsystem contained in the element.
sysUpTime String Internal use only
uuid String
equipment * Collection<Equipment>
The instances of Equipment (or any of its subclasses) that realize this instance of a NetworkResource subclass.
groups Set<Group> Groups containing the ManagedElement.
protocolEndpoint Set<ProtocolEndpoint>
The set of instances of a ProtocolEndpoint subclasses that support this instance of a NetworkResource subclass.
The table below lists the operations available to retrieve ManagedElement data from RESTCONF via the http protocol. All URLs require basic authentication and can produce:
application/xml
application/yang.data+xml
application/json
application/yang.data+json The first URL retrieves all the ManagedElement entities in the database. The next URL returns a specific ManagedElement entity by its business key. Enter the values of the attributes shown in the braces, but do not include the braces.
This object supports the fully-qualified domain name (FDN) attribute, which is unique for all ManagedElement objects. You may use the FDN as a query parameter to retrieve a specific ManagedElement object as follows: http://<host>/restconf/data/v1/epnm-restconf-xmp-im-ext-managedelement:ManagedElement?fdn=<value>
Where <host> is the host name or IP address of the Cisco EPN Manager Server and <value> is the value of the FDN attribute for the object to retrieve.
Sample Response Data
4.2.1.1 JSON This sample is formatted and edited for clarity and length.
This interface provides the operations to retrieve Chassis entities. This object is a specialization of Equipment that can contain other pieces of Equipment (such as enclosure, frame, and so on).
Chassis Data
The table below lists the attributes in the Chassis object. Associated objects are represented by a collection, for one-to-many associations, or an attribute of the object type for one-to-one or many-to-one associates. The role of the object(s) in the association provides the name for association attributes. The API traverses selected associations, usually of one-to-many cardinality, to allow retrieval of a hierarchy of objects in a single request. Attribute names of such associations are followed by an asterisk (*). To prevent cycles in the retrieval or divide the hierarchy into manageable pieces, other associations are summarized as a string with an entry giving the object type, name, and business key for each object in the collection. Some attributes may not be displayed since null values and empty associations are not included in the response.
Chassis Data Data Type Description
instanceId int Instance identifier of entity in the database.
businessKey String String representation of attribute value(s) that uniquely identify the entity or instanceId if no business key defined.
administrativeStateCode String ** Deprecated. Will be replaced by an enumerated attribute (possibly a lookup table) after a proper model review **\r\nThe administrative state (locked, unlocked, and so on). The administrative state is the result of an administrative action performed by administrator and/or EMS/NMS SW.
assemblyNumber String Indicates the manufacturing assembly number, which is the 'hardware' identification.
assemblyRevision String Indicates the revision of the entity within the assemblyNumber.
cleiCode String This object represents the CLEI (Common Language Equipment Identifier) code for the physical entity. If the physical entity is not present in the system, or does not have an associated CLEI code, the value of this object will be null.\r\n\r\nFrom-CISCO-ENTITY-ASSET-MIB : ceAsset.cleI
description String an optional description of the entity.
deviationNumber String Revision number (signifying a minor deviation) of a module, port adapter, and so on. Typically this number is required in FN (Field Notice) reports provided to customers by a HW vendor.
entPhysicalContainedIn String ## Internal use only ##
entPhysicalIndex String ## Internal use only ##
equipmentType EquipmentTypeEnum
An indication of the general hardware type of the physical entity. This should be set to the standard enumeration value that most accurately indicates the general class of the physical entity or the primary class if there is more than one.
If no appropriate standard registration identifier exists for this physical entity, the value 'other' is returned.
fdn String The fully qualified domain name (FDN) for the equipment (or equipment subclass) instance
hardwareVersion String The vendor-specific hardware revision string for the physical entity. The preferred value is the hardware revision identifier actually printed on the component itself (if present). If no specific hardware revision string is associated with the physical component, or if this information is unknown, this will contain a zero-length string.
isFRUable MultiStateEnum Indicates whether this physical entity is considered a 'field replaceable unit' by the vendor.
isRackMountable boolean Indicates whether the Chassis can be mounted in a Rack.
isReportingAlarmsAllowed
MultiStateEnum Indicates whether alarm reporting for this resource is allowed (can be set to Not_applicable).
manufacturedDate datetime Contains the date of manufacturing of the equipment. If the manufacturing date is unknown or not supported, the value of 0 is assigned.
manufacturer String The name of the manufacturer of this physical component. The preferred value is the manufacturer name string actually printed on the component itself (if present). If the manufacturer name string associated with the physical component is unknown to the agent, this object will contain a zero-length string.
name String the name of the entity
nrFreeSlots int Indicates the number of free slots the chassis has.
nrSlots int The number of slots in the chassis available for plugin modules.
operationalStateCode String ** Deprecated. Will be replaced by an enumerated attribute (possibly a lookup table) after a proper model review **\r\nThe operational state (operable or inoperable) of the equipment.
owningEntityId String ## Internal use only ##
partNumber String Manufacturer's part number.
position String ** Deprecated. Will be removed after EquipmentHolder is put back in the model **\r\nThe name of the container(s) that the Equipment is in, or null if is not contained (for example, chassis).
productFamily String The name of a group of products derived from a common product platform. For example, Catalyst 4000, MDS 900. Product family can be uniquely determined via the productId in Cisco's products databases that contain the product, product series, product families, and their relationship.
productId String The vendor-specific model name identifier string associated with this physical component. The preferred value is the customer-visible part number, which might be printed on the component itself. The productId generated by the device is often referred to as the \\\'base PID\\\'.\r\n\r\nFor some applications, PIDs must go through a validation process; the resulting PID is referred to as a \\\'validated PID\\\'.
productName String The official name given to a product. For example, Cisco 10720 Router or Cisco 10720, Cisco 12000 Series Six-Port DS3 Line Card or 6-Port DS3.
serialNumber String The vendor-specific serial number string for the physical entity. The preferred value is the serial number string actually printed on the component itself (if present). If a serial number is unknown or nonexistent, the SerialNumber will be left null. Note that not every physical component has (or needs) a serial number. Physical entities, which are not FRU (field replaceable) do not need their own unique serial number. This item is used for composing the UDI SID (see attribute 'udi').
serviceState EquipmentServiceStateEnum
Denotes the service state of a physical entity from the point of view of the management application. It indicates whether the entity is in service, out of service, under maintenance, and so on.
slotConfig String ** Deprecated. Will be removed after EquipmentHolder is put back in the model **\r\nAn indication of which slots in the chassis have modules inserted. This is an integer value with bits set to indicate configured modules. It can be interpreted as a sum of f(x) as x goes from 1 to the number of slots, where f(x) = 0 for no module inserted and f(x) = exp(2, x-1) for a module inserted. Based on the MIB definition, it can only represent (the first) 16 slots in a Chassis.
subclassname String The name of the object type
udi String Universal Device Identifier. The UDI is composed by concatenating the following values:\r\nPID = Equipment.partNumber\r\nVID = Equipment.hardwareVersion\r\nSN = Equipment.serialNumber
vendorEquipmentType String An indication of the vendor-specific hardware type of the physical entity. Represents an independently extensible type identification value. It can, for example, indicate a particular subtree with further MIB definitions, or define a particular type of protocol or hardware (for example, 1.3.6.1.4.1.9.12.3.1.9.3.131).\r\nSee CISCO-ENTITY-VENDORTYPE-OID-MIB.
connectors * Set<PhysicalConnector>
The set of instances of PhysicalConnectors contained in this piece of Equipment.
containedEquipment * Set<Equipment> A set of instances of Equipment contained in this instance of Equipment.
occupiedHolders Set<EquipmentHolder>
The EquipmentHolders occupied by this piece of Equipment.\nOther pieces of Equipment provide these Holders. For example: A Module can occupy one or two Slots provided by a Chassis.
providedHolders Set<EquipmentHolder>
A collection of the EquipmentHolders provided by this Chassis. Other pieces of Equipment can occupy these Holders. For example: A Chassis can provide many Slots, and Modules can occupy the Slots.
Retrieve Chassis instance by database instance id Note: Do not use braces for the <id>.
This object supports the fully-qualified domain name (FDN) attribute, which is unique for all Chassis objects. You may use the FDN as a query parameter to retrieve a specific Chassis object as follows: http://<host>/restconf/data/v1/xmp-im-physical-resource-module-chassis:Chassis?fdn=<value>
Where <host> is the host name or IP address of the Cisco EPN Manager server and <value> is the value of the FDN attribute for the object to retrieve.
Sample Response Data
4.3.1.1 JSON This sample is formatted and edited for clarity and length.
This interface provides the operations to retrieve Equipment entities. The object represents a piece of hardware that has some well specified function (for example, a line card, memory board, or power supply).
Equipment Data
The table below lists the attributes in the Equipment object. Associated objects are represented by a collection, for one-to-many associations, or an attribute of the object type for one-to-one or many-to-one associates. The role of the object(s) in the association provides the name for association attributes. The API traverses selected associations, usually of one-to-many cardinality, to allow retrieval of a hierarchy of objects in a single request. Attribute names of such associations are followed by an asterisk (*). To prevent cycles in the retrieval or divide the hierarchy into manageable pieces, other associations are summarized as a string with an entry giving the object type, name, and business key for each object in the collection. Some attributes may not be displayed since null values and empty associations are not included in the response.
Equipment Data Data Type Description
instanceId int Instance identifier of entity in the database.
businessKey String String representation of attribute value(s) that uniquely identify the entity or instanceId if no business key defined.
administrativeStateCode String ** Deprecated. Will be replaced by an enumerated attribute (possibly a lookup table) after a proper model review **\r\nThe administrative state (locked, unlocked, and so on). The administrative state is the result of an administrative action performed by administrator and/or EMS/NMS SW.
assemblyNumber String Indicates the manufacturing assembly number, which is the 'hardware' identification.
assemblyRevision String Indicates the revision of the entity within the assemblyNumber.
cleiCode String This object represents the CLEI (Common Language Equipment Identifier) code for the physical entity. If the physical entity is not present in the system, or does not have an associated CLEI code, the value of this object will be null.\r\n\r\nFrom-CISCO-ENTITY-ASSET-MIB : ceAsset.cleI
description String An optional description of the entity.
deviationNumber String Revision number (signifying a minor deviation) of a module, port adapter, and so on. Typically this number is required in FN (Field Notice) reports provided to customers by a HW vendor.
entPhysicalContainedIn String ## Internal use only ##
entPhysicalIndex String ## Internal use only ##
equipmentType EquipmentTypeEnum
An indication of the general hardware type of the physical entity. This should be set to the standard enumeration value that most accurately indicates the general class of
the physical entity or the primary class if there is more than one. If no appropriate standard registration identifier exists for this physical entity, the value 'other' is returned.
fdn String The fully qualified domain name (FDN) for the equipment (or equipment subclass) instance.
hardwareVersion String The vendor-specific hardware revision string for the physical entity. The preferred value is the hardware revision identifier actually printed on the component itself (if present). If no specific hardware revision string is associated with the physical component, or if this information is unknown, this will contain a zero-length string.
isFRUable MultiStateEnum Indicates whether this physical entity is considered a 'field replaceable unit' by the vendor.
isReportingAlarmsAllowed
MultiStateEnum Indicates whether alarm reporting for this resource is allowed (can be set to Not_applicable).
manufacturedDate datetime Contains the date of manufacturing of the equipment. If the manufacturing date is unknown or not supported, the value of 0 is assigned.
manufacturer String The name of the manufacturer of this physical component. The preferred value is the manufacturer name string actually printed on the component itself (if present). If the manufacturer name string associated with the physical component is unknown to the agent, this object will contain a zero-length string.
name String The name of the entity.
operationalStateCode String ** Deprecated. Will be replaced by an enumerated attribute (possibly a lookup table) after a proper model review **\r\nThe operational state (operable or inoperable) of the equipment.
owningEntityId String ## Internal use only ##
partNumber String Manufacturer's part number.
position String ** Deprecated. Will be removed after EquipmentHolder is put back in the model **\r\nThe name of the container(s) that the Equipment is in, or null if is not contained (for example, chassis).
productFamily String The name of a group of products derived from a common product platform. For example, Catalyst 4000, MDS 900. Product family can be uniquely determined via the productId in Cisco's products databases that contain the product, product series, product families, and their relationship.
productId String The vendor-specific model name identifier string associated with this physical component. The preferred value is the customer-visible part number, which might be printed on the component itself. The productId generated by the device is often referred to as the \\\'base PID\\\'.\r\n\r\nFor some applications, PIDs must go through a validation process; the resulting PID is referred to as a \\\'validated PID\\\'.
productName String The official name given to a product. For example, Cisco 10720 Router or Cisco 10720, Cisco 12000 Series Six-Port
serialNumber String The vendor-specific serial number string for the physical entity. The preferred value is the serial number string actually printed on the component itself (if present). If a serial number is unknown or nonexistent, the SerialNumber will be left null. Note that not every physical component has (or needs) a serial number. Physical entities, which are not FRU (field replaceable) do not need their own unique serial number. This item is used for composing the UDI SID (see attribute 'udi').
serviceState EquipmentServiceStateEnum
Denotes the service state of a physical entity from the point of view of the management application. It indicates whether the entity is in service, out of service, under maintenance, and so on.
subclassname String The name of the object type.
udi String Universal Device Identifier. The UDI is composed by concatenating the following values:\r\nPID = Equipment.partNumber\r\nVID = Equipment.hardwareVersion\r\nSN = Equipment.serialNumber.
vendorEquipmentType String An indication of the vendor-specific hardware type of the physical entity. Represents an independently extensible type identification value. It can, for example, indicate a particular subtree with further MIB definitions, or define a particular type of protocol or hardware (for example, 1.3.6.1.4.1.9.12.3.1.9.3.131).\r\nSee CISCO-ENTITY-VENDORTYPE-OID-MIB.
connectors * Set<PhysicalConnector>
The set of instances of PhysicalConnectors contained in this piece of Equipment.
containedEquipment * Set<Equipment> A set of instances of Equipment contained in this instance of Equipment.
occupiedHolders Set<EquipmentHolder>
The EquipmentHolders occupied by this piece of Equipment.\nOther pieces of Equipment provide these Holders. For example: A Module can occupy one or two Slots provided by a Chassis.
Operations
All URLs require basic authentication and can produce:
application/xml
application/yang.data+xml
application/json
application/yang.data+json The following table lists the operations available to retrieve Equipment data from RESTCONF via the http protocol:
Retrieve Equipment instance by database instance id. Note: Do not use braces for the <id>.
This object supports the fully-qualified domain name (FDN) attribute, which is unique for all Equipment objects. You may use the FDN as a query parameter to retrieve a specific Equipment object as follows: http://<host>/restconf/data/v1/xmp-im-physical-resource-module-equipment:Equipment?fdn=<value>
Where <host> is the host name or IP address of the Cisco EPN Manager server and <value> is the value of the FDN attribute for the object to retrieve.
Sample Response Data
4.4.1.1 JSON This sample is formatted and edited for clarity and length.
{"ns2.EquipmentInstances": [
"Equipment": [
{
"description": "A901-12C-F-D Motherboard with Built-in 12GE,
This interface provides the operations to retrieve Module entities. The object represents a physical module or adapter card.
Module Data
The following table lists the attributes in the Module object. Associated objects are represented by a collection, for one-to-many associations, or an attribute of the object type for one-to-one or many-to-one associates. The role of the object(s) in the association provides the name for association attributes. The API traverses selected associations, usually of one-to-many cardinality, to allow retrieval of a hierarchy of objects in a single request. Attribute names of such associations are followed by an asterisk (*). To prevent cycles in the retrieval or divide the hierarchy into manageable pieces, other associations are summarized as a string with an entry giving the object type, name, and business key for each object in the collection. Some attributes may not be displayed since null values and empty associations are not included in the response.
Module Data Data Type Description
instanceId int Instance identifier of entity in the database.
businessKey String String representation of attribute value(s) that uniquely identify the entity or instanceId if no business key defined
administrativeStateCode String ** Deprecated. Will be replaced by an enumerated attribute (possibly a lookup table) after a proper model review **\r\nThe administrative state (locked, unlocked, and so on). The administrative state is the result of an administrative action performed by administrator and/or EMS/NMS SW.
assemblyNumber String Indicates the manufacturing assembly number, which is the 'hardware' identification.
assemblyRevision String Indicates the revision of the entity within the assemblyNumber.
cleiCode String This object represents the CLEI (Common Language Equipment Identifier) code for the physical entity. If the physical entity is not present in the system, or does not have an associated CLEI code, the value of this object will be null.\r\n\r\nFrom-CISCO-ENTITY-ASSET-MIB : ceAsset.cleI
description String an optional description of the entity.
deviationNumber String Revision number (signifying a minor deviation) of a module, port adapter, and so on. Typically this number is required in FN (Field Notice) reports provided to customers by a HW vendor.
entPhysicalContainedIn String ## Internal use only ##
entPhysicalIndex String ## Internal use only ##
equipmentType EquipmentTypeEnum
An indication of the general hardware type of the physical entity. This should be set to the standard enumeration value that most accurately indicates the general class of the physical entity or the primary class if there is more than one. If no appropriate standard registration identifier exists for this physical entity, the value 'other' is returned.
fdn String The fully qualified domain name (FDN) for the equipment (or equipment subclass) instance.
hardwareVersion String The vendor-specific hardware revision string for the physical entity. The preferred value is the hardware revision identifier actually printed on the component itself (if present). If no specific hardware revision string is associated with the physical component, or if this information is unknown, this will contain a zero-length string.
isFRUable MultiStateEnum
Indicates whether this physical entity is considered a 'field replaceable unit' by the vendor.
isInlinePowercapable boolean Indicates whether a module is capable of providing inline power through its ports. Populated based on the module type: \\\'wsx6348rj45\\\', \\\'wsx4148rj45v\\\', \\\'cevCat6kWsx6348Rj45\\\', \\\'wsf6kvpwr\\\', and \\\'cpu-3845-2ge\\\' are inline power capable. Others are not capable.
isReportingAlarmsAllowed MultiStateEnum
Indicates whether alarm reporting for this resource is allowed (can be set to Not_applicable).
manufacturedDate datetime Contains the date of manufacturing of the equipment. If the manufacturing date is unknown or not supported, the value of 0 is assigned.
manufacturer String The name of the manufacturer of this physical component. The preferred value is the manufacturer name string actually printed on the component itself (if present). If the manufacturer name string associated with the physical component is unknown to the agent, this object will contain a zero-length string.
moduleIndex int ## Internal use only ##
name String The name of the entity.
nrFreeSlots int Indicates the number of free slots the chassis has.
nrPorts int Specifies the number of ports that are supported by the module.
nrSlots int The number of slots in the chassis available for plugin modules.
operationalStateCode String ** Deprecated. Will be replaced by an enumerated attribute (possibly a lookup table) after a proper model review **\r\nThe operational state (operable or inoperable) of the equipment.
owningEntityId String ## Internal use only ##
partNumber String Manufacturer's part number.
position String ** Deprecated. Will be removed after EquipmentHolder is put back in the model **\r\nThe name of the container(s) that the Equipment is in, or null if is not contained (for example, chassis).
productFamily String The name of a group of products derived from a common product platform. For example, Catalyst 4000, MDS 900. Product family can be uniquely determined via the productId in Cisco's products databases that contain the product, product series, product families, and their relationship.
productId String The vendor-specific model name identifier string associated with this physical component. The preferred value is the customer-visible part number, which might be printed on the component itself. The productId generated by the device is
often referred to as the \\\'base PID\\\'.\r\n\r\nFor some applications, PIDs must go through a validation process; the resulting PID is referred to as a \\\'validated PID\\\'.
productName String The official name given to a product. For example, Cisco 10720 Router or Cisco 10720, Cisco 12000 Series Six-Port DS3 Line Card or 6-Port DS3.
resetReason ModuleResetReasonTypeEnum
Identifies the reason for the last reset performed on the module.
resetReasonDescription String A description qualifying the module reset reason specified in resetReason. Examples: command xyz, missing task, switch over, watchdog timeout, and so on.
serialNumber String The vendor-specific serial number string for the physical entity. The preferred value is the serial number string actually printed on the component itself (if present). If a serial number is unknown or nonexistent, the SerialNumber will be left null. Note that not every physical component has (or needs) a serial number. Physical entities, which are not FRU (field replaceable) do not need their own unique serial number. This item is used for composing the UDI SID (see attribute 'udi').
serviceState EquipmentServiceStateEnum
Denotes the service state of a physical entity from the point of view of the management application. It indicates whether the entity is in service, out of service, under maintenance, and so on.
subclassname String The name of the object type
udi String Universal Device Identifier. The UDI is composed by concatenating the following values:\r\nPID = Equipment.partNumber\r\nVID = Equipment.hardwareVersion\r\nSN = Equipment.serialNumber
vendorEquipmentType String An indication of the vendor-specific hardware type of the physical entity. Represents an independently extensible type identification value. It can, for example, indicate a particular subtree with further MIB definitions, or define a particular type of protocol or hardware (for example, 1.3.6.1.4.1.9.12.3.1.9.3.131).\r\nSee CISCO-ENTITY-VENDORTYPE-OID-MIB.
connectors * Set<PhysicalConnector>
The set of instances of PhysicalConnectors contained in this piece of Equipment.
containedEquipment * Set<Equipment>
A set of instances of Equipment contained in this instance of Equipment.
occupiedHolders Set<EquipmentHolder>
The EquipmentHolders occupied by this piece of Equipment.\nOther pieces of Equipment provide these Holders. For example: A Module can occupy one or two Slots provided by a Chassis.
Operations
All URLs require basic authentication and can produce:
Retrieve Module instance by database instance id Note: Do not use braces for the <id>.
This object supports the fully-qualified domain name (FDN) attribute, which is unique for all Module objects. You may use the FDN as a query parameter to retrieve a specific Module object as follows: http://<host>/restconf/data/v1/xmp-im-physical-resource-module-module:Module?fdn=<value>
Where <host> is the host name or IP address of the Cisco EPN Manager Server and <value> is the value of the FDN attribute for the object to retrieve.
This interface provides the operations to retrieve PhysicalConnector entities. Represents a connector that can transmit signals or power when in a connection.
PhysicalConnector Data
Associated objects are represented by a collection, for one-to-many associations, or an attribute of the object type for one-to-one or many-to-one associates. The role of the object(s) in the association provides the name for association attributes. The API traverses selected associations, usually of one-to-many cardinality, to allow retrieval of a hierarchy of objects in a single request. Attribute names of such associations are followed by an asterisk (*). To prevent cycles in the retrieval or divide the hierarchy into manageable pieces, other associations are summarized as a string with an entry giving the object type, name, and business key for each object in the collection. Some attributes may not be displayed since null values and empty associations are not included in the response. The following table lists the attributes in the PhysicalConnector object:
PhysicalConnector Data
Data Type Description
instanceId int Instance identifier of entity in the database.
businessKey String String representation of attribute value(s) that uniquely identify the entity or instanceId if no business key defined
description String an optional description of the entity
entAliasLogicalIndexOrZero
String ## Internal use only ##
entPhysicalContainedIn
String ## Internal use only ##
entPhysicalIndex
String ## Internal use only ##
name String the name of the entity
owningEntityId
String ## Internal use only ##
subclassname String The name of the object type.
vendorEquipmentType
String An indication of the vendor-specific hardware type of the physical entity. Represents an independently extensible type identification value. It can, for example, indicate a particular subtree with further MIB definitions, or define a particular type of protocol or hardware (for example, 1.3.6.1.4.1.9.12.3.1.9.3.131).\r\nSee CISCO-ENTITY-VENDORTYPE-OID-MIB.
Operations
All URLs require basic authentication and can produce:
This interface provides the operations to retrieve PhysicalProtocolEndpoint entities. This object represents the end point related to a physical protocol. Note that this is NOT a physical entity, but a logical entity that represents media information. In contrast, the associated physical entity, such as a USB connector, is represented by the PhysicalConnector class or one of its subclasses.
PhysicalProtocolEndpoint Data
The table below lists the attributes in the PhysicalProtocolEndpoint object. Associated objects are represented by a collection, for one-to-many associations, or an attribute of the object type for one-to-one or many-to-one associates. The role of the object(s) in the association provides the name for association attributes. The API traverses selected associations, usually of one-to-many cardinality, to allow retrieval of a hierarchy of objects in a single request. Attribute names of such associations are followed by an asterisk (*). To prevent cycles in the retrieval or divide the hierarchy into manageable pieces, other associations are summarized as a string with an entry giving the object type, name, and business key for each object in the collection. Some attributes may not be displayed since null values and empty associations are not included in the response.
PhysicalProtocolEn
dpoint Data
Data Type Description
instanceId int Instance identifier of entity in the database.
businessKey String String representation of attribute value(s) that uniquely
identify the entity or instanceId if no business key
defined.
alarmStatus AlarmSeverityEnum ## Internal use only ##\r\nRaw MIB data - parsed into
supportedSpeeds and supportsAutoSpeed
clocking PhysicalLayerClockingE
num
Indicates the clocking mechanism that is being used.
comments String Contains comments added to a subclass of
ProtocolEndpoint.
description String An optional description of the entity.
doAutoNegotiation boolean Indicates whether the element should negotiate speed,
The set of instances of ProtocolEndpoint subclasses that
are part of a protocol stack (ISO), of which this instance
of PhysicalProtocolEndpoint is the lowest layer (is said
to \'contain the endpoints in the stack\').
forwardingRelations
hipEnd
ForwardingRelationship
End
The set of instances of ForwardingRelationship for this
instance of FREnd (it is one side of the association
class).
lowerLayerPEP Set<ProtocolEndpoint> The set of instances of ProtocolEndpoint subclasses that
serve as a lower layer in a protocol stack for this
instance of a ProtocolEndpoint subclass. The lower layer
PEPs are said to provide connectivity to the upper layer
PEPs.
upperLayerPEP Set<ProtocolEndpoint> The set of instances of ProtocolEndpoint subclasses that
serve as upper layers in a protocol stack for this
instance of a ProtocolEndpoint subclass. This instance
(and possibly others) are said to provide connectivity to
the upper layer PEPs.
Operation
All URLs require basic authentication and can produce:
application/xml
application/yang.data+xml
application/json
application/yang.data+json The table below lists the operations available to retrieve PhysicalProtocolEndpoint data from RESTCONF via the HTTP protocol.
This object supports the fully-qualified domain name (FDN) attribute, which is unique for all PhysicalProtocolEndpoint objects. You may use the FDN as a query parameter to retrieve a specific PhysicalProtocolEndpoint object as follows: http://<host>/restconf/data/v1/xmp-im-connectivity-modulephysicalprotocolendpoint:PhysicalProtocolEndpoint?fdn=<value>
Where <host> is the host name or IP address of the Cisco EPN Manager server and <value> is the value of the FDN attribute for the object to retrieve.
Sample Response Data
4.7.1.1 JSON Following is the sample code formatted and edited for clarity and length.
This interface provides the operations to retrieve InterfaceProtocolEndpoint entities. This object represents entries in the IF-MIB IfTable or their equivalent in IOS or config-file.
InterfaceProtocolEndpoint Data
The table below lists the attributes in the InterfaceProtocolEndpoint object. Associated objects are represented by a collection, for one-to-many associations, or an attribute of the object type for one-to-one or many-to-one associates. The role of the object(s) in the association provides the name for association attributes. The API traverses selected associations, usually of one-to-many cardinality, to allow retrieval of a hierarchy of objects in a single request. Attribute names of such associations are followed by an asterisk (*). To prevent cycles in the retrieval or divide the hierarchy into manageable pieces, other associations are summarized as a string with an entry giving the object type, name, and business key for each object in the collection. Some attributes may not be displayed since null values and empty associations are not included in the response.
InterfaceProtocolEndpoint Data
Data Type Description
instanceId int Instance identifier of entity in the database.
businessKey String String representation of attribute value(s) that uniquely identify the entity or instanceId if no business key defined.
adminStatus IfAdminStatusEnum Represents the desired state of the interface.
alarmStatus AlarmSeverityEnum ## Internal use only ##\r\nRaw MIB data - parsed into supportedSpeeds and supportsAutoSpeed
comments String Contains comments added to a subclass of ProtocolEndpoint.
description String An optional description of the entity.
entAliasMappingIdentifier
String ## Internal use only ##
fdn String The fully qualified domain name (FDN) for the equipment (or equipment subclass) instance
ifIndex String ## Internal use only ##
ifSpeed LongQuantity Specifies an estimate of the interface's current bandwidth in bits per second. For interfaces that do not vary in bandwidth or for those where no accurate estimation can be made, this should contain the nominal bandwidth. For a sublayer that has no concept of bandwidth, this object should be zero.
isConnectorPresent MultiStateEnum Indicates whether the interface sublayer has a physical connector.
isFloatingPep boolean Indicates whether a ProtocolEndpoint is related to a ResourceAccessPoint. If not, this ProtocolEndpoint is known as a floating PEP.
isPromiscuous boolean Indicates whether this interface only accepts packets/frames that are addressed to its hosting network element. This object has a value of true when the station accepts all packets/frames transmitted on the media. The
value true is only legal on certain types of media; otherwise the attribute is set to false. This value does not affect the reception of broadcast and multicast packets/frames by the interface.
isTrapEnabled boolean False if the interface is confured to not send the traps.
lagEndName String ## Internal use only ##
layerRate LayerRateEnum
locationIndex unsignedInt ## Internal use only ##
mtosiLabel String !!! this attribute is only to be used by the MTOSI NBI. It's format and population cannot be relied upon and may change without notice !!!
mtu int Represents the size in octets of the largest packet that can be sent/received on the interface. For interfaces that are used for transmitting network datagrams, this is the size of the largest network datagram that can be sent on the interface.
name String The name of the entity.
operStatus IfOperStatusEnum Represent the current operational state of the interface.
owningEntityId String ## Internal use only ##
subclassname String The name of the object type.
supportedMTUs NumericRange Indicates the MTU range supported by the Ethernet interface.
type IFTypeEnum The type of endpoint, as defined by IANA. Reference: IF-MIB : ifType
forwardingRelationshipEnd
ForwardingRelationshipEnd
The set of instances of ForwardingRelationship for this instance of FREnd (it is one side of the association class).
lowerLayerPEP Set<ProtocolEndpoint>
The set of instances of ProtocolEndpoint subclasses that serve as a lower layer in a protocol stack for this instance of a ProtocolEndpoint subclass. The lower layer PEPs are said to provide connectivity to the upper layer PEPs.
upperLayerPEP Set<ProtocolEndpoint>
The set of instances of ProtocolEndpoint subclasses that serve as upper layers in a protocol stack for this instance of a ProtocolEndpoint subclass. This instance (and possibly others) are said to provide connectivity to the upper layer PEPs.
Operations
All URLs require basic authentication and can produce:
Retrieve InterfaceProtocolEndpoint instance by database instance id Note: Do not use braces for the <id>.
This object supports the fully-qualified domain name (FDN) attribute, which is unique for all InterfaceProtocolEndpoint objects. You may use the FDN as a query parameter to retrieve a specific InterfaceProtocolEndpoint object as follows: http://<host>/restconf/data/v1/xmp-im-connectivity-module-interfaceprotocolendpoint:InterfaceProtocolEndpoint?fdn=<value>
Where <host> is the host name or IP address of the Cisco EPN Manager server and <value> is the value of the FDN attribute for the object to retrieve.
Sample Response Data
4.8.1.1 JSON This sample is formatted and edited for clarity and length.
This section describes the format of the fully-qualified domain name (FDN) attribute. FDN attribute is unique for each object that supports it. You may use the FDN as a query parameter to retrieve a specific object appending the following query to the URL that retrieves all objects of a particular type: ?fdn=<value> Where: <value> is the value of the FDN attribute listed in the table below. The following table list the object classes, inherited superclass, and FDN computation format.
Object Class Superclass FDN Format
Group - N/A
ManagedElement - See ManagedElement FDN Format
Chassis Equipment See Equipment FDN Format
Equipment - See Equipment FDN Format
Module Equipment See Equipment FDN Format
PhysicalConnector - N/A
PhysicalProtocolEndpoint ProtocolEndpoint See ProtocolEndpoint FDN Format
InterfaceProtocolEndpoint ProtocolEndpoint See ProtocolEndpoint FDN Format
ManagedElement FDN Format 5.1
A ManagedElement object represents a device managed by the Cisco EPN Manager. The FDN for managed elements contains the management domain (currently a fixed value, ‘CISCO_EPNM’, but this may change in future releases) and the name attribute of the device. Note: The device name must be globally unique to ensure that the ManagedElement FDN is unique. The format is as follows: MD/CISCO_EPNM/ME/<me.name>
Where: <me.name> is the value of the ManagedElement’s name attribute. For example: MD/CISCO_EPNM/ME/cvg.cisco.com
An Equipment object represents a piece of hardware that has some well-specified function (for example, a line card, memory board, or power supply).This object class has several subclasses, as shown in the table above. The FDN for equipment objects starts with the management domain (currently a fixed value, ‘CISCO_EPNM’, but this may change in future releases) and the name of the device that contains it. The rest of this FDN is calculated based on which attributes of the Equipment object are populated to ensure that the FDN is unique. The format is as follows: MD/CISCO_EPNM/ME/<me.name>/EQ/<ComputedName>
Where: <me.name> is the value of the containing ManagedElement’s name attribute <ComputedName > is as calculated below to ensure a unique value for the equipment object’s name.
Equipment Attributes ComputedName
<e.partnumber> is null and <e.entphysicalindex> is numeric
name=<e.name>;partnumber=<e.vendorequipmenttype>
<e.partnumber> is null and <e.entphysicalindex> is non-numeric
To summarize, <e.entphysicalIndex> contains the name if its value is non-numeric, otherwise the name in is the <e.name> attribute. If the <e.partnumber> value is defined, it is supplied as the part number value, otherwise <e.vendorequipmenttype> is substituted for it. For example: Case 1:
An object type that is of a subclass of ProtocolEndpoint represents a potential or actual start, end, or intermediate point of connectivity. For example, IP and Ethernet interfaces are represented by subclasses of the ProtocolEndpoint. The table, below, defines the types of end points.
Acronym Name Description
CTP Connection Termination Point Termination for links and subnetwork connections.
FTP Floating Termination Point Termination point not associated with a physical port, such as an Ethernet Flow Point.
PTP Physical Termination Point Termination point supported by a port, but not the physical connector itself, which is a separate object.
This section provides details about the supported RESTCONF Containment Hierarchy for RESTCONF/YANG interfaces.
Physical Inventory YANG Containment Hirarchy 6.1
The Class Diagram below shows the YANG Containment Hierarchy for Physical Inventory objects. Associated objects are represented by a collection, for one-to-many associations, or an attribute of the object type for one-to-one or many-to-one associates. The role of the object(s) in the association provides the name for association attributes. The API traverses selected associations, usually of one-to-many cardinality, to allow retrieval of a hierarchy of objects in a single request. Attribute names of such associations are followed by an asterisk (*). To prevent cycles in the retrieval or divide the hierarchy into manageable pieces, other associations are summarized as a string with an entry giving the object type, name, and business key for each object in the collection. Some attributes may not be displayed since null values and empty associations are not included in the response.
Physical Inventory YANG Containment Hierarchy - High Level Class Diagram
To be provided.
Physical Inventory YANG Containment Hierarchy – Detailed Class Diagram
Additional REST APIs details can be accessed this link. Although these documents refer to Cisco Prime Infrastructure, the content is also applicable to Cisco EPN Manager.
Filtering lets you limit the results of a request based on the value of specific Resource attributes. Filtering is supported for all request types
Filtering Syntax
Filtering on a given attribute of a resource is simple. The documentation gives a list of all attributes for a given resource. For example, to get a device with a given name, you may use the following: https://<server_name>/restconf/data/v1/epnm-restconf-xmp-im-ext-managedelement:ManagedElement?name=ASR9K
A set of operators allows you to refine the filter in many ways. For example, to get the list of all devices that start with a pattern, you may use wildcards on the <name>: https://<server_name>/restconf/data/v1/epnm-restconf-xmp-im-ext-managedelement:ManagedElement?name=ASR*
The results of a query can be filtered using the value of one or a combination of multiple attributes. https://<server_name>/restconf/data/v1/epnm-restconf-xmp-im-ext-managedelement:ManagedElement?name=ASR*&communicationState=REACHABLE
URL encoding
When forming a filter URL it must comply with URL encoding rules and only contain characters from the ASCII character-set. Filter values may frequently contain characters from outside the ASCII set, e.g. space: https://<server_name>/restconf/data/v1/epnm-restconf-xmp-im-ext-managedelement:ManagedElement?description=sample description
These must be converted into a valid ASCII format. URL encoding replaces unsafe ASCII characters with a "%" followed by two hexadecimal digits. A web browser will automatically encode the entered URL before sending it. However, if for example you are using a client coded with cURL you will need to do the encoding yourself. For example space character should be encoded as "%20".
Advanced Filtering
Advanced filtering can be applied to attributes if the criteria conforms to the following table. The first two rows show how to control how the filter combines multiple criteria parameters (separated the ampersand ‘&’ as usual). The “and” (conjunction) and “or” (disjunction) operators are supported, although it is not necessary to use “or” since it is the default. Note that “and” and “or” cannot combined: the selected operator applies to all the criteria.
Sorting lets you control the order in which resources are returned. They can be sorted in Ascending or Descending order based on user preference. Sorting is enabled using the .sort (attribute_name) query parameter. Sorting is supported for all request types. For example, to sort a list of Devices by their latest collection times, you may use the following URL: https://<server_name>/restconf/data/v1/epnm-restconf-xmp-im-ext-managedelement:ManagedElement?.sort(+collectionTime)
Ascending vs. Descending
Ascending or Descending order is controlled by adding a "+" or "-" in front of the attribute name.
To sort based on collectionTime in ascending order, use the + sign (the default):
Paging lets you control the number of records returned by a request and page through the results. Paging is supported for all request types. To page results, use the .maxCount and .firstIndex parameters. Examples:
a. To get the first four results (results 0 to 3), you can use:
Filtering, Sorting and Paging can be combined as long as the combination adheres to the rules of each of the features. Examples: 1. http://<server_name>/restconf/data/v1/epnm-restconf-xmp-im-ext-
Several commercially available clients are available to exercise the RESTCONF/YANG interface. Use the API specification to create HTTP GET requests to send through these clients. Such tools allow the customer to explore the interface and troubleshoot problems. Two examples are:
Postman–A Google Chrome App which sends HTTP requests specified by the user and displays the response in raw or pretty format.
SoapUI by SMARTBEAR–This application also sends and receives HTTP information. It provides support for automated tests.
In production, the customer’s bespoke software will communicate with the Cisco EPN-Manager using the RESTCONF/YANG API over HTTP. The exact sequence of the requests depends on the customer application. Packet tracing tools, such as Wireshark, can be used to identify problems.