Table Of Contents

Best Practices for Integration BQL Parsing

Possible Changes in IMO Between Two Successive Releases

Best Practices

Use an Existing XML Parser Implementation

Do Not Rely on the Order of the Properties Inside the XML

Do Not Count or Validate the Number of Properties

Do Not Assume the Type of the Property, Parse it from the BQL

Keep the Data Hierarchical Structure

ID Parsing Should be Bullet Proofed Against 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 may present expansions in the Cisco ANA model. The list below provides the details of the 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:

a. The BQL's XML outputs can contain elements in a different order than what is expected.

b. The number of properties in an output can be changed between versions.

c. The property's type can be changed, namely, an integer can be changed to a string.

d. Each Object in the BQL model has an ID. For example:

{[MCNetwork][MCVM(IP=64.103.124.178)][Avm(AvmNumber=600)]}

Each value between the "[]" brackets represents an element and then "()" 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, namely, search for a specific property iterate on all properties until the property is found, rather than looking for it in a specific place.

e. It is possible for an IMO to contain an additional object in addition to its own objects, namely, the model in the new version will contain additional information.

Best Practices

In order to avoid the impact of Cisco ANA model changes, it is recommended that you use the best practices described in this section.

The recommended best practices include the following:

•Use an Existing XML Parser Implementation

•Do Not Rely on the Order of the Properties Inside the XML

•Do Not Count or Validate the Number of Properties

•Do Not Assume the Type of the Property, Parse it from the BQL

•Keep the Data Hierarchical Structure

•ID Parsing Should be Bullet Proofed Against the Addition of Properties

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. It is highly 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

Although it may appear that the order of the properties inside a BQL response is always fixed, do not rely on this. XML ISO does not define the order and therefore the BQL response does not define the order between the different properties. Getting 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 may be sent, which contain 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 may be extended with additional properties across different versions of Cisco ANA, so validating the number of properties may produce an error. Instead, parse the properties you expect to receive in a way that any addition will 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> 

May 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 the BQL

Property types are declared in the IMO, and may change from Cisco ANA version to version. Property types should be parsed, and then compared to the expected type in order to detect any changes.

Example

For example, the property:

<DeviceSerialNumber type="String">21293957</DeviceSerialNumber>

May 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 it will be easier to adjust or disregard.

Example

For example, an IMO like:

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

May produce a hierarchical structure such as:

IFWComponentContainer

ID

FWComponents

IRoutingEntity

ID

Name

ScriptMetadataOids

	com.sheer.framework.imo.Oid

	com.sheer.framework.imo.Oid

	com.sheer.framework.imo.Oid

ID Parsing Should be Bullet Proofed Against the Addition of Properties

Each Object in the BQL model has an ID, which is formatted, for example, as follows:

{[MCNetwork][MCVM(IP=64.103.124.178)][Avm(AvmNumber=600)]}

Each value between the "[]" brackets represents an element, and then "()" represents an element property and 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 are searching for a specific property iterate, search for it on all the 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 will not be 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 For information regarding IMO and API changes from version to version see the Cisco Active Network Abstraction Release Notes.

---