BVE FlexAPI Protocol Reference

The Business Visibility Engine (BVE) in NetVigil handles the distributed architecture transparently and provides a common interface for provisioning, data and report retrieval. Through the BVE, you can access the provisioning database and real-time statistics.

The BVE server is accessed via a text based protocol over a TCP socket. Protocol messages can be sent from programs written in C, Java, Perl or any other language.

An alternative to accessing the BVE Server directly is to use the NetVigil Perl API described in Chapter 20, "NetVigil Perl API".

17.1.1 Connecting to the Server

Communication with the BVE Server consists of two phases - a connection establishment phase and a command-execution phase. The connection establishment phase is where a remote client provides authentication information to the server in the form of a login id that is associated with a Department, and the corresponding password. Once the authentication information has been verified, all subsequent commands sent to the server will be executed with the permissions and privileges of the specified Department. It is possible to change the privilege level at any point in the command-reply phase by entering new authentication information.

Once the connection establishment phase has been completed, the client application may send one command at a time and wait to receive a reply (possibly consisting of multiple lines of output) from the server.

A client application establishes a connection to the BVE Server by opening a TCP/IP socket, using the hostname/ip of the server that is hosting the provisioning database, and a pre-defined port number specified in dge.xml (default port number is 7661). Upon establishment of the TCP session, the server will greet the client with a welcome message following the rules outlined below. The client may optionally send client-side information, e.g. client software version.

17.1.2 Disconnecting from the server

When the client application would like to disconnect from the NetVigil platform, it should issue a disconnect request instead of simply closing the socket connection. This will allow the server to perform proper cleanup before disconnecting the session.

Also if the BVE Server does not receive anything from the client for an extended period, the session will timeout and disconnect the client from the BVE Server. The default timeout is currently 15 minutes.

17.2 Command/Reply formatting rules

The commands sent by a client and responses sent back by the server must adhere to the following formatting conventions:

Client Command Format

Each client command is composed of a single line of text terminated by a newline character. A carriage return followed by a newline (\r\n) is considered to be the same as a newline character (\n) alone.

Client commands may or may not require additional parameters. Each parameter consists of the option name and value, separated by equal sign (=) and enclosed in quotes. Multiple parameters should be separated by a comma (,) and space. Example "command1=value1", "command2=value2"... If a parameter supports multiple values, the values should be separated by a comma (,). Example: "command1=value1,value2,...".

No whitespace characters should appear in the argument name. No whitespace should occur between the argument name and the equal (=) delimiter. Whitespace that occurs after the equal (=) is considered to be part of the argument value.

Double-quotes are not permitted as part of the value.

For each client command, the server will respond with a response code indicating success or failure, and optionally some descriptive text indication actions taken.

If a client command produces a reply with more than one line of output, the server will respond with 203 response code (see below). Each set of output will be terminated with a newline (\n) and the end of the array will be indicated with a newline (\n) by itself.

Command and parameter names are NOT case sensitive.

Parameters for any command may appear in any order following the command.

Certain parameters indicate a value of <regexp>, which indicates that the parameter may point to a non-unique value. You can use an asterisk (*) as a wildcard in such case. For example, dev* would match device1 and Device B but not my device. However, *dev* would match all three

Parameters which indicate <value> require a value which is already present in the database, while <new_value> indicates a new value to be inserted into the database.

All date/time should be specified in YYYYMMDDhhmm format and in GMT.

For startTime, a blank value (or zero [0]) indicates 24 hours ago and for endTime, it indicates now.

timezone_value is specified in format listed at http://www.timezoneconverter.com/cgi-bin/zonehelp.tzc?cc=US

For Device, Test, and Container specific commands, a special parameter "userName=<value>" is available to admin users. When used, the object would be created/deleted/etc. as the specified user.

Server Response Format

The server will always respond (to client initiated commands/requests) with text of the following format:

and response code is a three digit numeric code which provides additional details about the status code.

Server response codes and their meanings
Response code	Meaning
200 level - informative messages
200	Server ready for initial handshake
201	Request accepted and processed, ready for next request
203	Request accepted, multi line response follows
298	Request accepted, server will halt
299	Session ended, server will close socket connection
300 level - debugging information (ignore)
301 - 399	Debug message. These messages will be printed before a 200, 400 or 500 level message
400 level - client side error (try again)
401	Authentication failure
402	Logged in user does not have permission to perform requested task
410	Unknown command - use 'help' for list of commands
411	Feature has not been implemented yet
412	Not enough parameters specified - use 'help command.name'
413	Invalid Parameter parameter specified - use 'help command.name'
420	One or more objects already exist
421	One or more of the objects requested does not exist
500 level - server side error
595	Communication failure with remote database, please try again later
596	Maintenance in progress, please try again later
597	Server too busy, please try again later
598	Backend failure, server will close socket connection
599	Server unavailable, server will close socket connection

17.2.1 Client Commands

Logout | Quit

Action.create

Create a new action. Using '0' for n_tests on notifyAfter or repeat parameters will send an immediate notification and will not repeat the notification respectively. It is possible to get notifications on multiple states by specifying different state names separated by '|' symbol for notifyOn parameter. Assigning a method of 'none' will delete that action item. Up to five methods (method1 through method5) can be defined for a single action.

Action.update

Update configuration information of one of more existing actions. If actionSerial and actionName are both given, then the action matching the serial number given by actionSerial will be updated with the name given by actionName. Omitting an action item implies intent to remove that particular item. So if there are two action items for the action profile, and you are updating the parameters for action item #2 (method2), you will need to include the details of method1 verbatim (available via action.list command) first, and then the updated parameters for method2. Otherwise action item #1 will be removed

Action.delete

Action.list

AdminGroup.x

The adminGroup commands are similar to the Department.x commands below in syntax which are described below. Please see the description of these commands below.

AdminClass.create

Create an administrative group. Administrative groups are assigned User Groups, and members of admin groups can access information on any device, that is part of a Department under a user group assigned to that particular admin group.

AdminClass.update

Update user group assignments or name of an existing admin group. If AdminClassSerial and groupName are both given, then the admin group name will be updated.

AdminClass.delete

AdminClass.list

Container.status

Displays summary of Containers that have been created. The aggregate severity of each Container is provided.

Department.create

Create new Department information. A user login of the same name as the newly created Department will also be created with the specified password.

Department.update

Department.delete

Delete an existing Department. Any login IDs, devices and tests associated with this Department would automatically get deleted as well.

Department.suspend

Suspend an existing Department. All login IDs associated with this Department would be locked out of the system and all devices/tests for the corresponding login IDs would also be suspended.

Department.resume

Unsuspend a previously suspended Department. All login IDs associated with this Department would be able to log into the system once again and all devices/tests for the corresponding login IDs would start to be monitored again.

Department.list

Device.create

Device.update

Update configuration information for one or more existing device(s). If deviceSerial and deviceName are both given, then the device name will be updated.

To change the IP address of a host, you must specify the new ip address in the newaddress parameter. An error will be generated if more than one host matches the search criterion while changing the IP address.

Device.delete

Delete configuration information for one or more device(s). All associated tests for the device(s) are automatically deleted as well.

Device.suspend

Device.resume

Device.list

List device information based on the search criteria. Multiple search criterion is not supported.

Device.status

Displays summary of devices being monitored. Tests for each device are displayed in same three-column manner as the web application.

DeviceDependency.create

DeviceDependency.delete

DeviceDependency.list

DGE.create

DGE.update

Update information for an existing DGE. If dgeSerial and dgeName are both given, the DGE name is updated.

DGE.delete

DGE.list

Event.list

List events for one or more devices and one or more tests configured on those devices for a certain time-frame. By specifying a certain type of event in eventType parameter, it is possible to display only events where the previous or current state was of that type. Output will be in the format:

Location.create

Location.update

Update information on an existing location. If both locationName and locationSerial are given, the location name is updated.

Location.delete

Delete an existing location. All DGEs at that location and all associated devices/tests on those DGEs are deleted automatically.

Location.list

Result.list

List test results for one or more devices and one or more tests configured for those devices for a certain time-frame.

Test.create

To create a ping test:

To create an SNMP test:

resultProcessDirective

Indicates what type of calculation to perform after polling the new value. Eg. when it is set to "percent", uses the polled value and maximum (configured) value to calculate percentage, which is the final result


Value	Description
0	NONE. No post processing is done on the result
1	PERCENT. The fetched value is divided by the provisioned maximum value to get the percent. Useful for disk utilization.
2	DELTA. Calculate the difference between the value retrieved in the previous test and the value retrieved in the current test.
3	RATE. Calculate the delta from the previous value and then divide by the time interval between the tests to calculate the rate per second.
4	DELTAPERCENT. Calculate the delta from the previous value, and then divide by the provisioned maximum value.
5	RATEPERCENT. Calculate the delta from the previous value, and then divide by the time interval between tests as well as the provisioned maximum value to get the percentage per second.
6	REVPERCENT. Calculate the `percent' and then subtract from 100 to get the `reverse'. Useful to convert disk full into disk free.

resultMultiplier

This allows you to modify the polled result. If the SNMP agent reports data in bytes, and you want use bits, set the resultMultiplier to 8. To convert KB into MB, the resultMultiplier will be 0.001. As anothe example, you can also multiply by 60 to convert rate from per second to per minute.

maxValue

This the the maximum post-processed value (not the max of the SNMP counter/gauge which is typically 2^32). So if you are meauring the traffic rate of an ethernet port, which has a test unit of kbps, the max value should be 10,000. When measuring disk space utilization, it holds the maximum size for the disk (partition) as reported by SNMP agent, which will be used for percentage calculation.

To create a port test:

To create an external test:

Test.update

Test.delete

Delete configuration information for one or more existing test(s). If a test name is given, then a device name is required.

Test.suspend

Test.resume

Test.suppress

Suppress the test result of one or more tests. When suppressed, the severity/state of the test will not affect the status displayed for the device/Department. When test severity changes (e.g. from Warning to Critical or from Unknown to Unreachable), the suppression is reset automatically.

Test.list

Display test configuration parameters for the tests matching the search criteria.

Test.status

Displays current status of the tests for the device specified. The search can be restricted to test names with certain pattern, or severity.

where the time_stamp and time_in_state are provided in YYYYMMDDhhmmss format. Note that the test name is displayed in the last field, and test serial number is the first field.

User.create

User.update

Update information for an existing user/login id. User login names cannot be updated, so if both loginSerial and loginName are given, the loginName is ignored.

User.delete

User.list

User.represent

Masquerade as a specific user (only available to admin users). Once executed, the permissions and privileges of the specified user will be inherited and any new Department, device and tests created will be created on behalf of the said user.

UserClass.create

UserClass.update

Update user group information. If both groupName and userClassSerial are given, then the user group name will be updated with groupName.

UserClass.delete

UserClass.list

17.3 Example

The following is an example of a telnet session where a new device and a test are created by directly connecting to the BVE Server on the TCP port 7661.