- Cisco Active Network Abstraction Customization User Guide, 3.6.5
Table Of Contents
Best Practices for Integration BQL Parsing
Possible Changes in IMO Between Two Successive Releases
Use an Existing XML Parser Implementation
Do Not Rely on the Order of the Properties Inside the XML Parser
Do Not Count or Validate the Number of Properties
Do Not Assume the Type of the Property; Parse it from BQL
Keep the Data Hierarchical Structure
ID Parsing Should Be Protected from the Addition of Properties
Best Practices for Integration BQL Parsing
This chapter describes the possible changes in IMO between two successive releases and the various best parsing practices when integrating to Cisco ANA via the BQL interface.
Possible Changes in IMO Between Two Successive Releases
Cisco ANA service packs might present expansions in the Cisco ANA model. The list below provides the details of possible changes. When coding against Cisco ANA BQL, it is important to avoid the impact of these changes when applying future service packs. See Best Practices for a description of the best practices for each of these items.
The following changes are possible between two successive releases:
•
The BQL XML output can contain elements in a different order from what is expected.
•
•
•
{[MCNetwork][MCVM(IP=64.103.124.178)][Avm(AvmNumber=600)]}
Each value between the square brackets ([]) represents an element while the information in parentheses [( )] represents an element property and value. When parsing this ID, do not rely on the order or number of these elements, only on their existence. That is, search for a specific property iteration on all properties until the property is found, rather than looking for it in a specific place.
•
Best Practices
To avoid the impact of Cisco ANA model changes, we recommend that you use the best practices described in this section.
The recommended best practices include:
•
•
•
•
•
•
Use an Existing XML Parser Implementation
Each Cisco ANA integration is usually written in a programming language, and most, if not all, of these programming languages have existing XML parser implementations. We strongly recommend that you use an existing XML parser rather than implementing a new one.
Do Not Rely on the Order of the Properties Inside the XML Parser
Although it can appear that the order of the properties inside a BQL response is fixed, do not rely on this. XML ISO does not define the order, and therefore the BQL response does not define the order of the different properties. Locating a specific property inside an element should be done by iterating on all of the properties inside an element until the requested property is found.
Note that in this example, the order of the colored keys can be switched.
Example
In different Cisco ANA versions, two IMO replies can be sent, each containing the same properties in a different order.
First IMO reply:
<IManagedElement><ID type="Oid">{[ManagedElement(Key=PE-South)]}</ID><CommunicationStateEnum type="Integer">3</CommunicationStateEnum><CpuUsage type="Integer">2</CpuUsage><DRAMFree type="Integer">33141168</DRAMFree><DRAMUsed type="Integer">413264</DRAMUsed><DeviceName type="String">PE-South</DeviceName><DeviceSerialNumber type="String">21293957</DeviceSerialNumber>...</IManagedElement>Second IMO reply:
<IManagedElement><ID type="Oid">{[ManagedElement(Key=PE-South)]}</ID><CommunicationStateEnum type="Integer">3</CommunicationStateEnum><DRAMFree type="Integer">33141168</DRAMFree><CpuUsage type="Integer">2</CpuUsage><DRAMUsed type="Integer">413264</DRAMUsed><DeviceName type="String">PE-South</DeviceName><DeviceSerialNumber type="String">21293957</DeviceSerialNumber>...</IManagedElement>Do Not Count or Validate the Number of Properties
The IMO model exposed through the BQL can be extended with additional properties across different versions of Cisco ANA, so validating the number of properties can produce an error. Instead, parse the properties you expect to receive in such a way that any addition does not affect your integration by producing errors.
Example
The following IMO:
<IManagedElement><ID type="Oid">{[ManagedElement(Key=PE-South)]}</ID><CommunicationStateEnum type="Integer">3</CommunicationStateEnum><CpuUsage type="Integer">2</CpuUsage><DRAMFree type="Integer">33141168</DRAMFree><DeviceName type="String">PE-South</DeviceName><DeviceSerialNumber type="String">21293957</DeviceSerialNumber>...</IManagedElement>can be extended with an additional property:
<IManagedElement><ID type="Oid">{[ManagedElement(Key=PE-South)]}</ID><CommunicationStateEnum type="Integer">3</CommunicationStateEnum><DRAMFree type="Integer">33141168</DRAMFree><CpuUsage type="Integer">2</CpuUsage><DRAMUsed type="Integer">413264</DRAMUsed><DeviceName type="String">PE-South</DeviceName><DeviceSerialNumber type="String">21293957</DeviceSerialNumber>...</IManagedElement>Do Not Assume the Type of the Property; Parse it from BQL
Property types are declared in the IMO, and might change from Cisco ANA version to version. Property types should be parsed, and then compared to the expected type to detect any changes.
Example
The following property:
<DeviceSerialNumber type="String">21293957</DeviceSerialNumber>Can change to:
<DeviceSerialNumber type="Integer">21293957</DeviceSerialNumber>Keep the Data Hierarchical Structure
When doing integrations with BQL responses, keep track of the Cisco ANA BQL output structure in the integration data. This way, when new hierarchy sons or parents appear, the changes are easier to adjust or disregard.
Example
For example, the following IMO:
<IFWComponentContainer><ID type="Oid">{[ManagedElement(Key=PE-South)][LogicalRoot][FWComponentContainer(Type=1)]}</ID><FWComponents type="IMObjects_Array"><IRoutingEntity><ID type="Oid">{[ManagedElement(Key=PE-South)][LogicalRoot][FWComponentContainer(Type=1)][RoutingEntity]}</ID><Name type="String">Default context</Name><ScriptMetadataOids type="com.sheer.framework.imo.Oid_Array"><com.sheer.framework.imo.Oid>{[Command(CommandId=ciscoscriptsrepository/add-loopback-interface)][ScriptMetadata(MetadataId=cisco)]}</com.sheer.framework.imo.Oid><com.sheer.framework.imo.Oid>{[Command(CommandId=ciscoscriptsrepository/add-static-route)] [ScriptMetadata(MetadataId=cisco)]}</com.sheer.framework.imo.Oid><com.sheer.framework.imo.Oid>{[Command(CommandId=ciscoscriptsrepository/show-ip-route)][Sc riptMetadata(MetadataId=cisco)]}</com.sheer.framework.imo.Oid></ScriptMetadataOids></IRoutingEntity></FWComponents><ScriptMetadataOids type="">Null</ScriptMetadataOids><TypeEnum type="Integer">1</TypeEnum></IFWComponentContainer>might produce a hierarchical structure such as:
IFWComponentContainerIDFWComponentsIRoutingEntityIDNameScriptMetadataOidscom.sheer.framework.imo.Oidcom.sheer.framework.imo.Oidcom.sheer.framework.imo.OidID Parsing Should Be Protected from the Addition of Properties
Each object in the BQL model has an ID, which is formatted; for example:
{[MCNetwork][MCVM(IP=64.103.124.178)][Avm(AvmNumber=600)]}Each value between the square brackets ( [ ] ) represents an element, while parentheses ( ( ) ) contain an element property and a value. When parsing the ID, do not rely on the order or the number of these elements or properties, just on their existence; in other words, if you search for a specific property iteration, search for it on all properties until the property is found, rather than looking for it in a specific place. In this way, if an element or a property is added, the integration is not affected.
Example
If you are searching for the port number in the following object ID:
<ID type="Oid">{[ManagedElement(Key=PE-South)][PhysicalRoot][Chassis] [Module][Port(PortNumber=FastEthernet1/0)]}</ID>and if an additional element named Slot was added to the object ID:
<ID type="Oid">{[ManagedElement(Key=PE-South)] [PhysicalRoot][Chassis][Slot(SlotNum=1)][Module][Port(PortNumber=FastEthernet1/0)]}</ID>The integration code that searches for the PortNumber property can be written in such a way that it will not fail as a result of adding the additional property.
Note
