Cisco Active Network Abstraction BQL User Guide, 3.6.1
Getting Started
Download this chapter
Getting StartedGetting Started
Download the complete book
PDF of Cisco ANA BQL User Guide, 3.6.1PDF of Cisco ANA BQL User Guide, 3.6.1 (PDF - 1 MB)
 Feedback

Table Of Contents

Getting Started

What Is BQL?

Quick Start—BQL Basics

Connecting to BQL

Connecting to BQL by SSL

BQL Commands

Device-List Report Example

The BQL Get Command


Getting Started

What Is BQL?

Cisco BQL (Broadband Query Language) is a generic machine interface language, implemented by the Cisco ANA Gateway, for general-purpose northbound integration. BQL covers all Cisco ANA functionality:

•Information reporting (for example, inventory, topology, fault, and so on.)

•Service activation

•System administration

The interface is based on XML messages over TCP sockets. All data sent to and returned from the system is formatted as XML messages, containing IMO (Cisco's internal information model) data objects.

Quick Start—BQL Basics

This section briefly describes the BQL interface and gives an example of how to use it for integration. Each of the topics referenced in this section is elaborated in subsequent sections. The section describes briefly:

•How to connect to the BQL interface.

•How to format a command.

•How to execute a command.

•How to interpret the result of a command.

•How to limit the scope of a command.

•How to register for data change notifications.

The explanations in this section are accompanied with sample software programs, written in PERL. However, BQL is not restricted to any specific programming language.

Connecting to BQL

The BQL interface is using a TCP socket transport. The Cisco ANA Gateway listens for incoming connection attempts on a well-known port, as follows:

•Protocol—TCP

•Port number—9002

•Socket type—Streamable

To open a BQL session, the connecting application must authenticate the session using a username and password (which has been previously defined within the Cisco system). The authentication command is: 

openconnection user=<Username> password=<Password>

Following is a Perl example of opening and authenticating a BQL session, with the Cisco ANA Gateway whose IP address is 192.168.2.110: 

use IO::Socket::INET;


my $sock = IO::Socket::INET->new(PeerAddr => '192.168.2.110',

 PeerPort => 9002,

 Proto    => 'tcp',

 Type     => SOCK_STREAM);

die "Cannot open socket" unless defined $sock;


print $sock "openconnection user='John' password='XYZ'\n.\n";


my $Recv;

my $LoginOK=0;

while (($Recv=<$sock>)!~ /^\./)

{

   if ($Recv =~ /.*success.*/)

   {

      print "Login OK\n";

      $LoginOK=1;

   }

}

if (!$LoginOK)

{

   print "Login failed\n";

   print $sock "exit\n.\n";

   $sock->close();

   exit;

}

Note The \n.\n EOT (end-of-text) sequence at the end of the commands, which will be explained in the next section.

To disconnect from the BQL interface, enter the command: 

exit\n.\n

Then close the connection to the Cisco ANA Gateway.

Connecting to BQL by SSL

The BQL interface is using SSL socket transport. The Cisco ANA Gateway listens for incoming connection attempts on a well-known port, as follows:

•Protocol—SSL

•Port number—9003

•Socket type—Streamable

Then open a BQL session, see the Connecting to BQL section.

BQL Commands

After the BQL session is authenticated, all commands and responses are formatted as plain-text XML messages. Each command has the following format: 

<command name="commandName">

  <param name="paramName1">

    <value>ParamValue1</value>

  </param>

  <param name="paramName2">

    <value>ParamValue2</value>

  </param>

...

</command>

Every command must end with an End-Of-Text (EOT) sequence, which is a <NewLine> character ("\n") followed by a dot in an empty line, as follows:

EOT:"\n.\n"

Therefore, every command will have the following format: 

<command name="commandName">

...

</command>\n.\n

The EOT sequence is also terminating all BQL replies. However, when receiving unsolicited notifications, the EOT sequence changes into the format

Notification EOT:"\n$\n"

Notifications are further explained in the section Specifying Properties vs. Aspects.

The following example demonstrates a BQL command that retrieves the list of all NEs managed by the system. The command is called DeviceList and has no parameters: 

<command name="DeviceList">

</command>

.

After sending the above command to the BQL socket, the socket connection blocks until the Cisco ANA Gateway finishes processing the query. Once finished, the Cisco ANA Gateway will respond with the list of all devices in the system, and will free the connection for further queries. The reply to the DeviceList command will be, for example, as follows: 

<?xml version="1.0" encoding="UTF-8"?>

<IMObjects_Array>

  <IManagedElement>

    <ID type="Oid">{[ManagedElement(Key=CBX500Lab)]}</ID>

    <CommunicationStateEnum type="Integer">3</CommunicationStateEnum>

    <DeviceName type="String">CBX500Lab</DeviceName>

    <ElementCategoryEnum type="Integer">2</ElementCategoryEnum>

    <ElementTypeEnum type="Integer">22</ElementTypeEnum>

    <IP type="com.sheer.types.IPAddress">192.168.2.70</IP>

    <InvestigationStateEnum type="Integer">2</InvestigationStateEnum>

    <SoftwareVersion type="String">04.02.01.00</SoftwareVersion>

    <SysContact type="String" />

    <SysDescription type="String">Lucent  Technologies CBX 500</SysDescription>

    <SysLocation type="String" />

    <SysName type="String">cbx500f</SysName>

    <SysUpTime type="java.util.Date">Wed Apr 30 16:17:04 IDT 2003</SysUpTime>

    <VendorEnum type="Integer">6</VendorEnum>

  </IManagedElement>

  <IManagedElement>

    <ID type="Oid">{[ManagedElement(Key=CBX_Sim_Iftach)]}</ID>

    <CommunicationStateEnum type="Integer">3</CommunicationStateEnum>

    <DeviceName type="String">CBX_Sim_Iftach</DeviceName>

    <ElementCategoryEnum type="Integer">2</ElementCategoryEnum>

    <ElementTypeEnum type="Integer">22</ElementTypeEnum>

    <IP type="com.sheer.types.IPAddress">30.30.30.70</IP>

    <InvestigationStateEnum type="Integer">2</InvestigationStateEnum>

    <SoftwareVersion type="String">04.02.01.00</SoftwareVersion>

    <SysContact type="String" />

    <SysDescription type="String">Lucent  Technologies CBX 500</SysDescription>

    <SysLocation type="String" />

    <SysName type="String">cbx500f</SysName>

    <SysUpTime type="java.util.Date">Mon May 05 16:16:51 IDT 2003</SysUpTime>

    <VendorEnum type="Integer">6</VendorEnum>

  </IManagedElement>

</IMObjects_Array>

The above XML reply represents a list of two devices (two Lucent CBX switches, with IP address 192.168.2.60 and 30.30.30.70). The data objects in the reply are based on the IMO information model, which is Cisco the internal, generic information model. The above list is an array of IMO objects of type IManagedElement (the IMO object that represents a NE).

Each data entity type in the Cisco system has a corresponding IMO object type, which is serialized by BQL into XML strings. The full set of all IMO objects is described in the IMO Reference Manual. See Chapter 2, "Understanding IMO" and Chapter 3, "IMO Specification" for further descriptions of IMO.

Device-List Report Example

Following is the full Perl example for retrieving a device list: 

use IO::Socket::INET;


# ------- Open a BQL session

my $sock = IO::Socket::INET->new(PeerAddr => '192.168.2.110',

 PeerPort => 9002,

 Proto    => 'tcp',

 Type     => SOCK_STREAM);

die "Cannot open socket" unless defined $sock;


print $sock "openconnection user='John' password='XYZ'\n.\n";

my $Recv;

my $LoginOK=0;

while (($Recv=<$sock>)!~ /^\./)

{

   if ($Recv =~ /.*success.*/)

   {

      print "Login OK\n";

      $LoginOK=1;

   }

}

if (!$LoginOK)

{

   print "Login failed\n";

   print $sock "exit\n.\n";

   $sock->close();

   exit;

}


# ----- Send command and retrieve reply

print $sock "<command name='DeviceList'></command>\n.\n";


my $Result = "";

while (($Recv=<$sock>) !~ /^\./ )

{

   $Result = $Result . $Recv; 

}


print $Result,"\n";


print $sock "exit\n.\n";

$sock->close();

The reply to the BQL command is returned from the Cisco ANA Gateway socket as a data stream. Therefore, the program has to run a loop of reading from the socket into the temporary variable $Recv, and concatenating it into the result variable $Result.

The BQL Get Command

The most commonly used BQL command is the GET command. It specifies the OID (object identifier) of a data entity in the system and returns the information on this object. The OID uniquely identifies any data entity in the system. The GET command can be used not only for reporting a single object, but also for reporting a Construct of objects, which is a hierarchy of related data objects (e.g. a NE with all its cards and ports, an end-to-end service path etc.). When retrieving data constructs, the specified OID serves as the "root" of the construct, from which the related objects are traversed.

Following is an example of a simple GET command: 

<command name="Get">   

  <param name="oid">

    <value>{[ManagedElement(Key=Fore251Lab)]}</value>   

  </param>   

  <param name="rs">  

    <value>   

      <key name="DeviceProperties">

        <key name="requiredProperties">

          <key name="*">

            <entry name="*"/>

          </key>

        </key>

      </key>

    </value>   

  </param> 

</command>

The query in this example will retrieve the properties of the Network Element (NE) identified by the OID {[ManagedElement(Key=Fore251Lab)]}. It has an additional parameter, the Retrieval Specification (RS). The RS defines the information scope of the query, by specifying what type of IMO objects to retrieve, what object relationships to traverse, and what properties to include/exclude for each returned object.

The retrieval specification is an XML string with the following format: 


<param name="rs">

  <value>

    <key name="[rs name]">

      <entry name="register">[true/false]</entry>

      <key name="requiredProperties">

        <key name=[* or IMO type]>

          <entry name=[* or property name]/>

          <entry name=[* or property name]/>

        </key>

      </key>

      <key name="excludedProperties">

        <key name=[* or IMO type]>

          <entry name=[* or property name]/>

          <entry name=[* or property name]/>

        </key>

      </key>

    </key>

  </value>

</param>

For example: 

<param name="rs">     

  <value>

    <key name="DeviceProperties">

    <key name="requiredProperties">

        <key name="com.sheer.imo.IManagedElement">

          <entry name="*"/>

        </key>

    </key>

  </key>

  </value>   

</param>

In this example the RS specifies the retrieval of only the device properties (IP Address, Type, Vendor, Uptime etc.).

The output of the above BQL GET example (device properties of the Network Element whose key is "Fore251Lab") will look like the following: 

<?xml version="1.0" encoding="UTF-8"?>

<IManagedElement>

  <ID type="Oid">{[ManagedElement(Key=Fore251Lab)]}</ID>

  <CommunicationStateEnum type="Integer">3</CommunicationStateEnum>

  <DeviceName type="String">Fore251Lab</DeviceName>

  <ElementCategoryEnum type="Integer">2</ElementCategoryEnum>

  <ElementTypeEnum type="Integer">13</ElementTypeEnum>

  <IP type="com.sheer.types.IPAddress">192.168.2.251</IP>

  <InvestigationStateEnum type="Integer">2</InvestigationStateEnum>

  <LogicalRoot type="ILogicalRoot">

    <ID type="Oid">{[ManagedElement(Key=Fore251Lab)][LogicalRoot]}</ID>

  </LogicalRoot>

  <PhysicalRoot type="IPhysicalRoot">

    <ID type="Oid">{[ManagedElement(Key=Fore251Lab)][PhysicalRoot]}</ID>

  </PhysicalRoot>

  <ProvisioningSupportedServices type="java.lang.String_Array">

    <java.lang.String>256_ILink</java.lang.String>

    <java.lang.String>384_Bizlink</java.lang.String>

    <java.lang.String>GSHDSL_256K_cbr</java.lang.String>

   /ProvisioningSupportedServices>

  <SoftwareVersion type="String">S_ForeThought_7.0.0 FCS-Patch 
(1.101625)</SoftwareVersion>

  <SysContact type="String">eli11</SysContact>

  <SysDescription type="String">Marconi ASX-1000</SysDescription>

  <SysLocation type="String">Sheer-labs</SysLocation>

  <SysName type="String">ATM SWITCH</SysName>

  <SysUpTime type="java.util.Date">Mon Apr 14 13:00:50 IDT 2003</SysUpTime>

  <VendorEnum type="Integer">5</VendorEnum>

</IManagedElement>

The retrieval specification allows registering for change notifications on the specified objects. When specifying register=true in the RS, the ANA platform will monitor changes in all the objects that are defined in the RS scope. Whenever it detects a change in any of the objects it sends an unsolicited notification of the change. Consider, for example, the following notification: 

<?xml version="1.0" encoding="UTF-8"?>

<IMObjects_Array>

  <IScalarNotification>

    <ID type="Oid">{[Notification(SequenceNumber=1201)(Time=1052837316305)]}</ID>

    <PropertyName type="String">SysName</PropertyName>

    <NewIMO type="IManagedElement">

      <ID type="Oid">{[ManagedElement(Key=ASAMLab)]}</ID>

      <SysName type="String">ATM Switch</SysName>

    </NewIMO>

  </IScalarNotification>

</IMObjects_Array>

This notification indicates that the property SysName has changed, in the IMO object of type IManagedElement, of the NE "ASAMLab". Further details on Retrieval Specifications and notifications can be found in the sections Retrieval Specifications and Specifying Properties vs. Aspects.

Integration Sequence summarizes the integration steps using the BQL. The steps are:

Step 1 Open TCP socket to the BQL interface.

Step 2 Authenticate using username and password.

Step 3 Send BQL commands to the Cisco ANA Gateway.

Step 4 Receive and parse the returned results.

Step 5 Optional: Register and receive change notifications.

Step 6 Close the connection with the BQL interface.

Figure 1-1 Integration Sequence