DCNM for SAN Web Services API
This chapter describes the DCNM for SAN (DCNM-SAN) Web Services application program interface (API). This chapter defines the APIs exposed by the Cisco DCNM for SAN Web Services feature.
Introduction to Cisco DCNM for SAN Web Services
Cisco DCNM for SAN (DCNM-SAN) Web Services provide application programming interfaces (APIs) that expose Cisco DCNM-SAN core software functionalities as remote procedure calls to third-party vendors. Software developers can use the APIs to design computer applications that interact with the Cisco DCNM-SAN Server over the network.
With Cisco DCNM-SAN, you can monitor MDS switch events, performance, and inventory, and you can perform administrative tasks. Applications can access Cisco DCNM-SAN Web Services through many protocols and data formats such as HTTP, HTTPS, XML, SOAP, and WSDL.
Cisco DCNM-SAN Web Services provide cross-platform operations. Web Services can interact with .NET applications, C++ applications, and applications written in other programming languages and Web Services must adhere to accepted conventions to make services interoperable with other applications. For this reason, Cisco DCNM-SAN Web Services must follow the Java API for XML Web Services (JAX-WS) specification. Cisco DCNM-SAN Web Services relies on JBoss Web Service (JBoss WS) as a service endpoint engine and as an entry point into the JAX-WS programming model. The framework also allows Cisco DCNM-SAN Web Services to become an integral part of the Cisco DCNM-SAN Server run-time environment.
Web Services Specifications
Web Services specifications combine together to provide interoperable protocols for security, communication, and syntax for representing data.
XML
XML is the data format that defines the structure of the message. XML Web Services architecture allows programs written in different languages on different platforms to communicate with each other in a standards-based way. XML Web Services expose useful functionality to Web users through a standard Web protocol (SOAP).
SOAP
Simple Object Access Protocol (SOAP) is the communications protocol for Web Services. SOAP is a specification that defines the XML format for messages. The advantage of SOAP is that it has been implemented on many different hardware and software platforms.
HTTP/HTTPS
HTTP/HTTPS is the transport layer of the service. HTTP/HTTPS allows data to traverse the network easily and is widely accepted. It is also considered as platform neutral. Every Cisco DCNM-SAN Web Services operation is through HTTP/HTTPS.
WDSL
A WSDL definition is an XML document with a root definition element from the http://schemas.xmlsoap.org/wsdl/ namespace. Cisco DCNM-SAN Web Services uses the WSDL document to publish which operations of DCNM-SAN are available. The definitions element can contain several other elements including types, message, portType, binding, and service, all of which come from the namespace. WSDL is published on FMServer at:
Logon Service
LogonWS makes IdentityManager’s operations available as Web Service calls. LogonWS allows the following operations:
requestToken
This method returns a token string that must be passed in as the header of the SOAP message. Once the username and password is authenticated using DCNM-SAN’s SecurityManager, the token is generated and is kept valid for the number of milliseconds specified in the expiration argument.
password—Password of the user.
validateToken
This method returns true or false depending on the validity of the token. If the token has expired, it returns false, or else it returns true.
Authentication or Token
To interact with DCNM-SAN Web Services, you must obtain a token through LogonWS and attach this token to the header message of every SOAP requests. DCNM-SAN Web Services verifies user credentials using a unique token string that is administered by LogonWS. At any given time, HTTPS should be deployed to secure the communication channel. The following example displays the format of the header message:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">Sas WS
SAN Service is an Enterprise Java Beans (EJB) component that manages SAN-related service requests and executes queries on DCNM-SAN for information. San WS checks with IdentityManager for authentication before performing the request. A valid token string indicates to San Service that the user is a DCNM-SAN user and that it must honor and execute the request. After retrieving the required information, it sends the result back to the user. SanWS logs errors in fms_ws.log. The service end-point interface (SEI) of SanWS defines the operations of the service, and sends them to the end users.
getFabricByIP
Returns the list of fabrics associated with the IP address of a given switch.
ipAddress—IP address of the switch.
List of all fabrics associated with the specific IP address.
getPmEntity
Returns the PM entity from the database.
getPmChartData
Returns the PM statistics of a specific RRD file.
PM statistics of a specific RRD file.
getFabricByKey
Returns the list of fabrics associated with the specified key.
List of all fabrics associated with the specified key.
getFabricBySwitchKey
Returns the list of fabrics associated with the specified seed switch key (WWN).
swkey—Seed switch key of the fabric.
List of all fabrics associated with the specified seed switch key.
getSwitchesByFabric
Returns the list of switches associated with the specified fabric key.
List of all fabrics associated with the specified fabric key.
getNeighborSwitches
Returns the list of neighboring switches associated with the specified WwnKey.
List of neighboring switches associated with the specified WwnKey.
Error Code: 300— General SAN Service exception.
Error Code: 201—Invalid argument in Web Service exception.
Error Code: 302—SAN does not find objects by query key exception.
getActiveServerNodes
Returns the list of all active DCNM for SAN servers.
List of all fabric servers that are active.
getFabricWithSnmpCredentail
Returns the list of fabrics (except the fabric with opening status) with the SNMP credentials.
List of all fabrics with their SNMP credentials.
Error Code: 300— General SAN Service exception.
getSwitchesByFabric
Returns the list of switches associated with the specified fabric key.
List of all fabrics associated with the specified fabric key.
getSwitch
Returns the list of switches on all the fabrics.
List of all fabrics associated with the specified fabric key.
getSwitchByKey
Returns the switch associated with the specified switch key object.
Switch associated with the specified switch key.
getSwitchIPByName
Returns the IP address associated with the specified system name or switch name.
sysname—Name of the system or switch.
IP address associated with the specified system name.
getSwitchIPByKey
Returns the IP address of the switch associated with the specified WwnKey object.
IP address associated with the specified WwnKey object.
getNeighborSwitches
Returns the list of neighboring switches associated with the specified WwnKey.
List of neighboring switches associated with the specified WwnKey.
Error Code: 300— General SAN Service exception.
Error Code: 201—Invalid argument in Web Service exception.
Error Code: 302—SAN does not find objects by query key exception.
getVsans
Returns the list of VSANs in the fabric associated with the specified fabric key.
List of VSANs in the fabric associated with the specified fabric key.
getVsan
Returns the VSAN in the fabric associated with the specified VSAN key object.
VSANs in the fabric associated with the specified VSAN key object.
getIsls
Returns the list of ISLs in the VSAN associated with the specified VSAN key.
Array of ISL objects in the VSAN associated with the specified VSAN key.
discoverFabric
This API opens the fabric. This function requires the IP address of the seed switch and SNMP credentials.
seed—IP address of the seed switch.
Boolean value is True if the discovery was successful.
Error Code: 300— General SAN Service exception.
Error Code: 201—Invalid argument in Web Service exception.
manageFabric
Returns true or false depending on manageability of the fabric.
Returns true if the fabric can be identified or managed. Returns false if the fabric cannot be identified or managed.
closeFabric
This function unmanages and closes a fabric.
purgeFabric
This function purges the specified fabric data both from the DCNM-SAN cache and database.
Error Code: 300— General SAN Service exception.
Error Code: 201—Invalid argument in Web Service exception.
Error Code: 302—SAN does not find objects by query key exception.
getEnclosures
Returns the list of all the enclosures known to DCNM-SAN.
getEndPortByKey
Returns the end port based on the switch WWN.
Returns the end port based on the switch WWN. Returns null if there are no end ports associated with the switch.
getEndPortAttachedToSw
Returns the end ports that are associated with a switch.
Returns the end ports based on switch.
getEnclosureByName
Returns the enclosure based on the name.
name—Name of the enclosure object.
getEnclosureByKey
Returns the enclosure based on the name.
name—Name of the enclosure object.
getEnclosureByPWwn
Returns the enclosures that are associated with a physical WWN.
wwn—Physical WWN of the switch.
Returns the enclosure based on physical WWN.
updateEnclosure
Update the enclosure with the value that is passed as parameter.
value—Value to update the enclosure.
updateEndportEnclosure
Update the end port enclosure with the value that is passed as parameter.
endportKey—Value for the end port key.
enclosureKey—Value for the enclosure key.
getHosts
Returns the list of all the host enclosures known to DCNM-SAN.
Returns the list of all the host enclosures known to DCNM-SAN.
getHost
Returns the name of hosts in a VSAN.
Returns the name of the hosts in tthe specified VSAN.
getHostByFabric
Returns the name of hosts in a fabric.
ValidationException is displayed if any of the following situation occurs:
Returns the name of the hosts in the specified VSAN.
getStorages
Returns the list of all the storage device enclosures known to DCNM-SAN.
An array of all the storage device enclosures known to DCNM-SAN.
getStorageByFabric
Returns the name of storage device enclosures in a fabric.
Returns the name of the storages in the specified fabric.
getHostPorts
Returns the list of all the host end ports in a fabric.
An array of all the host ports in a fabric.
getVsanIp
Returns the IP address of a VSAN.
vsanid—Unique identifier of the VSAN.
Error Code: 300— General SAN Service exception.
Error Code: 201—Invalid argument in Web Service exception.
getIvrEnfZoneSetName
Returns the fabric IVR-enforced zone set name.
getIvrEnfZoneSetNumber
Returns the fabric IVR-enforced zone number.
getIvrEnfZoneSetActivateTime
Returns the fabric IVR-enforced zone set activate time.
Time stamp in the long integer format.
Error Code: 300— General SAN Service exception.
Error Code: 201—Invalid argument in Web Service exception.
getIvrActiveZonesetChecksum
Returns the IVR active zone set checksum.
Error Code: 300— General SAN Service exception.
Error Code: 201—Invalid argument in Web Service exception.
useFcAlias
Returns all the FC aliases used by the fabric.
FC aliases used by the fabric.
getEnfZoneSet
Returns all theVSAN enforced zone sets.
getEnfZoneSetName
Returns all the VSAN enforced zone set names.
getEnfZoneSetName
Returns all the VSAN enforced zone set name.
Error Code: 300— General SAN Service exception.
Error code: 201—Invalid argument in Web Service exception.
getFCAliasesByVsan
Returns all the FC aliases for the VSAN.
getZoneModeByVsan
Returns zone operation modes for VSAN.
Error Code: 300— General SAN Service exception.
Error Code: 201—Invalid argument in Web Service exception.
getZoneAttributesByVsan
Returns zone attributes for VSAN.
Zone Manager WS - SEI
addZoneMemberToZone
Adds a new zone member to the specific zone.
addZoneMemberToZoneAlias
Adds a zone member to the zone alias.
createZoneMemberInZone
Creates a zone member in the specified zone.
createZoneMemberInZoneAlias
Creates a zone member in the specified zone alias.
deActivateZoneset
Returns the operational status of the zone set.
Operational status of the zone set.
getEnfZoneSetName
Returns the name of the enforced zone set.
getIvrActiveZonesetChecksum
Returns the IVR active zoneset checksum.
getIvrEnfZoneNumber
Returns the fabric IVR enforced zone number.
Error Code: 300—General SAN Service exception.
Error Code: 201—Invalid argument in Web Service exception.
getIvrEnfZoneSetActivateTime
Returns the fabric IVR enforced zone set activate time.
System time as the number of seconds elapsed since the start of the Unix epoch at 1 January 1970 00:00:00 UT.
getIvrEnfZoneSetName
Returns the fabric IVR enforced zone set name.
getZoneAttributes
Returns all the attributes for the zone.
Error Code: 300—General SAN Service exception.
Error Code: 201—Invalid argument in Web Service exception.
List of zone attributes for the VSAN.
getZoneCapabilitiesByFabric
Returns the zone information associated with the specified fabric key.
getZoneCapabilitiesByVsan
Returns all zone information for the VSAN.
getZoneModeByVsan
Returns the list of zone modes for the VSAN.
Zone information for the VSAN.
Statistics WS
getEndDeviceStatisticsByAlias
Returns the statistics of the end devices by device alias.
getEthPortStatisticsByKey
Returns the statistics of the Ethernet port.
getEthPortStatisticsBySwitch
Returns the statistics of the Ethernet port based on a switch.
getFcPortStatistics
Returns the statistics of the Fibre Channel port.
getFcPortStatisticsByKey
Returns the statistics of the Fibre Channel port based on the switch WWN.
getFcPortStatisticsBySwitch
Returns the statistics of the Fibre Channel port based on a switch.
Security WS
getAaaMaxServer
Returns a value for the maximum number of server entries in a server group of the AAA configuration.
Maximum number of server entries in a server group of the AAA configuration.
getAaaMaxAppServer
Returns a value for the maximum number of server entries in the AAA configuration for an application type.
Maximum number of server entries in a server group in the AAA configuration.
isClearAcctLogSet
Checks if the clear accounting log is set.
isMSCHAPRequired
Returns a boolean value to indicate if MSCHAP authentication mechanism is required for authenticating a user.
Boolean value to indicate if MSCHAP authentication mechanism is required for authenticating a user.
getAaaAppServerGroups
Returns the AAA server groups for a specific application type.
getAaaServerGroups
Returns all the AAA server group entries (a server group consists of a number of AAA servers implementing the same AAA protocol).
getSSHEnabled
Returns a boolean value to indicate if the SSH is enabled.
isTelnetEnabled
Returns a boolean value to indicate if Telnet is enabled.
getPkiCert
Returns certificate information of a PKI trustpoint.
getPkiTrustPoint
Returns the PKI trust point information, which consists of the key pair name, a list of revocation methods, and the contact HTTP URL of the external OCSP server for certificate revocation.
getFeatureControls
Returns all of the feature control names and their respective statuses.
getIkeCfgPolicies
Returns the policy that is used to set up the IKE tunnels.
getIkeCfgInitiators
Returns the IKE initiator configuration information.
getIPsecGlobalCfg
Returns the IPsec tunnel configuration information.
getIfsFromCryptoMap
Returns the interface name from the IPsec cryptomap.
Protocol WS
queryInterfaceFspfConfig
Returns the FSPF configuration on the interface pertaining to the specified VSAN.
vsanid—Unique identifier of the VSAN
FSPF configuration settings on the interface of a specified VSAN.
getFcipProfilesBySwitch
Returns FCIP profiles based on a switch.
getFcipTunnelsBySwitch
Returns FCIP tunnels based on a switch.
getFcipTunnelByLinkIndex
Returns FCIP tunnels based on a switch.
getFcipTunnelByLinkIfIndex
Returns FCIP tunnels based on a switch.
Error Code: 300— General SAN Service exception.
Error Code: 201—Invalid argument in Web Service exception.
getFcipTunnelErrorsBySwitch
Returns FCIP tunnels errors based on a switch.
getIpSettingsBySwitch
Returns IP settings from the switch.
getIpSettings
Returns IP settings from the switch and port.
IP settings from the switch and port.
Cluster WS - SEI
Service end point interface (SEI) of Cluster WS defines the operations of the service. These methods are published to the end users.
getSwitchesByFabricKey
Returns all the switches related to a fabric key.
Event WS - SEI
Service end point interface (SEI) of Event WS defines the operations of the service. These methods are published to the end users.
getCallHomeSysInfo
Returns system information about the CallHome feature.
getEmailMaxEntries
Returns the maximum number of e-mail address entries for the CallHome feature.
getEmailSetup
Returns the e-mail setup details of the CallHome feature.
Inventory WS - SEI
Service end point interface (SEI) of Inventory WS defines the service end point interface for Inventory Web Service. These methods are published to the end users.
getPowerSuppliesBySwitchWwnKey
Returns name of the power suppies by switch.
Error Code: 300 or 201—SAN service error or Invalid Argument
getPowerSuppliesBySwitchSnKey
Returns name of the power suppies by switch.
Error Code: 300 or 201—SAN service error or Invalid Argument
getPowerSuppliesBySwitchIP
Returns name of the power supplies by switch IP address.
Error Code: 300 or 201—SAN service error or Invalid Argument
getCardsBySwitchWwnKey
Returns name of the cards from a switch key.
Error Code: 300 or 201—SAN service error or Invalid Argument
getCardsBySwitchSnkey
Returns name of the cards from a switch key.
Error Code: 300 or 201—SAN service error or Invalid Argument
getCardsBySwitchIP
Returns name of the cards by switch IP address.
Error Code: 300 or 201—SAN service error or Invalid Argument
getFansBySwitchWwnKey
Returns name of the fans by switch key.
Error Code: 300 or 201—SAN service error or Invalid Argument
getFansBySwitchSnKey
Returns name of the fans by switch key.
Error Code: 300 or 201—SAN service error or Invalid Argument
getFansBySwitchIP
Returns name of the fans by switch IP address.
Error Code: 300 or 201—SAN service error or Invalid Argument
getChassisBySwitchWwnKey
Returns name of the chassis by switch key.
Error Code: 300 or 201—SAN service error or Invalid Argument
getChassisBySwitchSnKey
Returns name of the chassis by switch key.
Error Code: 300 or 201—SAN service error or Invalid Argument
getChassisBySwitchIP
Returns name of the chassis by switch IP address.
Error Code: 300 or 201—SAN service error or Invalid Argument
getAllHbas
Returns name of the hosts by host IP address.
Error Code: 300 or 201—SAN service error or Invalid Argument
getHbaByWwn
Returns name of the hosts by host IP address.
Error Code: 300 or 201—SAN service error or Invalid Argument
getLicensesBySwitchWwnKey
Returns name of the licenses used by the switch.
Error Code: 300 or 201—SAN service error or Invalid Argument
getLicensesBySwitchIP
Returns name of the licenses used by the switch.
Error Code: 300 or 201—SAN service error or Invalid Argument
Error Codes
![]()
Note DCNM-SAN Web Services supports server federation. Service requests to SanWS, SecurityWS, ProtocolWS, EventWS, and InventoryWS automatically dispatches the calls to the correct server in the federation. If you are using server federation, the following methods do not automatically mediate to the corresponding server in the federation:
SanWS:
getEnclosures()
getEndports()
getFabricByIP()
getHosts()
getStorages()
getSwitchIPByName()
getSwitches()
InventoryWS:
getAllHbas()
getLicenseFlags()
In those specific instances, you might need to rely on ClusterWS to determine the server that you need to send the request.