Cisco Prime Provisioning API Programmer Guide, 7.2

Setting up the Client

Note An example client, EventListener, provided with the Prime Provisioning software, is a simple servlet that listens to the notifications servlet. Use this example to create your own client for event notifications. See Appendix B, “Implementing a Notification Server,” for more information.

The client must register for events. Use the following properties to enable notifications and to indicate where notification messages should be sent.

• notification.clientEnabled—Used to turn notification forwarding on and off. To enable the client, set notification.clientEnabled=true.
• notification.clientHost—The machine running the event notification receiving program.
• notification.clientPort—The listener port to open on the receiving machine.
• notification.clientMethod—The method, or program, to contact on the receiving machine. The clientMethod is defined in the Tomcat web.xml file. The notification web.xml file (located in $PRIMEF_HOME/resources/webserver/tomcat/webapps/notification/WEB-INF) identifies two servlets. One is the notificationServlet and the other is the eventListener (EventReceivingServlet program) servlet.

– The notificationServlet is the Prime Provisioning program responsible for collecting and forwarding events of interest.

– The clientHost, clientMethod, and clientPort are used to construct a URL.

– The clientMethod/notification/servlet/eventListener is mapped to the eventListener servlet.

• notification.clientRegFile—Located in /opt/vpnsc/iscadmin/resources/nbi/notification/clientReg.txt, this file contains the events of interest to be forwarded. See Appendix B, “Implementing a Notification Server,” for a complete list of the events that can be collected.

To define the events are of interest to the client, change the notification.clientRegFile so that it points to a file that contains all interested events. For example, if you have the following lines in this file:

The first line defines events that add PIX objects. The second line defines events that modify PIX objects. The third line defines all PersistentTask related events. (The “>” symbol is a wildcard to represent any match.)

Tip Use com.cisco.vpnsc.repository.> to represent any repository change event.

Remote Authentication

The notification server allows Prime Provisioning events to be delivered using an HTTP interface to a remote system. If your remote system requires authentication, use these properties to set up the remote user and password information.

• notification.remoteUsername
• notification.remotePassword

These properties allows the Prime Provisioning notification server to respond to remote authentication requests, which is required by certain systems prior to establishing a connection. The default values for these properties is null.

Notification Responses

Event notifications are sent in the form of XML responses. The operation for event notification is deliverEvent. For each event, the following information is returned in the XML response:

• IndicationTime
• IndicationType=

– InstCreation

– InstDeletion

– InstModification

– InstStateChange (for service requests)

• InstClassName
• LocatorId
• Name

If the state of a service request changes, additional information is returned under InstIndicationDetails:

• Previous_SR_State
• Current_SR_State
• Description

See the following example:

SQL-Based Reports

The execQuery operation allows you to execute a direct search of the Prime Provisioning database and to specify the form of the output data. The query language is a subset of SQL and supports queries specified with parameters and objects defined in the XML schema. A response to an execQuery returns data records and can be sent in an XML response or saved to a file. File data can be in either XML format or comma separated value (CSV) format. See “Output for Reports” section for more information.

Note You can specify a delimiter other than commas, if necessary. The Prime Provisioning API supports a single character delimiter.

Use the execQuery operation to query the main Prime Provisioning repository or the SLA repository.

• The main Prime Provisioning repository holds data for objects representing devices and VPN network elements. It also contains data collected from devices by the collection server, and task data, which is used by the scheduler.
• The SLA repository contains SLA tables populated with the data gathered by SLA probes.

The SQL search criteria for execQuery is defined as follows:

• Select property list—A comma-separated list of property names related to the individual classes specified in the From clause. An asterisk (*) can be used to specify ALL of the properties of a class.
• From class list—A comma-separated list of class names. If more than one class name is specified, the classes must be related by an association, which is a condition in the Where clause.
• Where conditions—Specifies the criteria by which results are selected. The criteria can be simple property comparisons.
• Orderby clause—Specifies the criteria by which results are sorted.

Tip If you are using an Oracle database, you should use aliases for your Select names because it has a 30 character limit.

Note The execQuery operation does not support aggregate functions or subqueries. Use the where clause for joins.

The body of the XML request contains the execQuery operation, the QueryLanguage, and the SQL search criteria, specified with the Query attribute. See the following example:

In this example:

• The operation is execQuery
• In the execQuery class, the QueryLanguage is WQL
• The search criteria for the execQuery class is; Select properties, Id, Name, and ContactInfo From any record with the class name Organization.

An execQuery request with the above search criteria returns the following records in XML format:

Canned Reports

Prime Provisioning provides canned reports for frequently requested report data. These canned reports can be used as is, copied, modified, or extended by customers. Canned reports are located in the $PRIMEF_HOME/resources/nbi/reports/ISC directory. This is the defaul location for canned reports.

Custom reports, which are canned reports that have been modified for a particular customer, are located in the $PRIMEF_HOME/resources/nbi/reports/custom directory. To use custom reports, you must change the property file to so that it points to this directory. See the following example:

Table 5-1Table 5-1Table 5-1Table 5-1 Table 5-1 describes the types of canned reports provided with Prime Provisioning.

Canned reports use the execReport operation in the XML request. The XML request provides the search criteria, and the response returns the report data.

See the following example of an XML request for the canned report; VPNReport:

Report Definitions

The search criteria for a canned report is derived from a report definition. The search criteria in the example XML request, vpn.name, pe_cisco_router.host_name, and mpls_sr.sr_state, correlate to parameters in the the report definition (meta file). Each canned report has an associated report definition file.

The report definition specifies report header information, search criteria, parameter definitions, filters, and sort order for the report output. The following sections show the different parts in a report definition.

Header

The header in the report definition lists the report name, the label, and report title.

Note There is no RBAC record filter in the current version of Prime Provisioning.

Search Criteria

The search criteria includes:

• Select property list—A comma-separated list of property names related to the individual classes specified in the From clause. An asterisk (*) can be used to specify ALL of the properties of a class.
• From class list—A comma-separated list of class names. If more than one class name is specified, the classes must be related by an association, which is a condition in the Where clause.
• Where conditions—Specifies the criteria by which results are selected. The criteria can be simple property comparisons.
• The search criteria in the report definition is the same as for execQuery

Note The filter sets in this meta definition (filterSet1 and filterSet2) are defined with the filter parameters (see Filters), and referenced in the SQL search criteria. See Named Filter Sets for more information.

Parameter Definitions

The parameter definitions associate objects and definitions in the Prime Provisioning meta file to use in the canned report. Parameter definitions can also define access parameters for each object and filter options. The parameters definitions used in the example XML request are indicated in bold.

Filters

The filter section lists the parameters that filters can to be applied to in this report definition. The items in bold indicate the parameters used in the example XML request.

Named Filter Sets

There can be additional filters with special references in the meta definition, called named filter sets. Named filter sets can be used when an SQL subqueries has its own where clause that requires user input. You can apply operators, arguments, and attributes (such as mandatory), to filters sets in the meta definition.

Sorting

This section of the report definition defines the default sort criteria. Use the paramDef name (not the label) to identify the parameters to sort. Note that the PE Device Name is sorted in ascending order (asc), and VPN Name is sorted in descending order (decs).

Output for Reports

The response to an execQuery or execReport request can be sent as an XML response or exported to an output file on the Prime Provisioning server. File data can be in XML format or comma separated value (CSV) format.

• Output in XML format is a typical XML response that contains data records separated by record elements. The XML format is the default for execQuery or execReport output data.
• Output in CSV format is data records separated by commas (or another specified delimiter). The first line of the output is the list of column labels. The following lines contain the records. See the following example:

To specify CSV format for the output data, you must add the filename, format, and delimiter in the first line of the XML response. To have the output data sent to a file (XML or CSV data), you define the filename and format in the first line of the execQuery and execReport XML requests. The first line is processed during the output and not during the query operation. See the following example:

In this example:

• filename=”/users/user1/tmp/querydata” is the location of the output file name.
• format=”csv” specifies that the output be in CSV format
• delimiters=”;” specifies that the output data be separated by semi-colons. This parameter is optional.
• maxRecords=”100” specifies that the API return no more than 100 records. This parameter is optional.

Use the following guidelines when choosing the format of the output data:

• If you specify XML, or do not specify a format, the output is returned in the form of an XML response.
• If you specify CSV, and send the output to a file, the output is CSV data only, no XML tags. This data cannot be sent across an HTTP connection. CSV data can be imported into a spreadsheet, or any reporting tool that supports a one character delimiter.
• If the file already exists, the response data overwrites this existing file.
• If you specify an output file, the XML response sent across the client connection lists the name of the file and a line count of the output data.
• If you specify an output file, report data is written to a file on the Prime Provisioning server.

Note The line count equals the number of records, plus one (the line for the column labels).

• If the API cannot write to this file, you receive an error.
• If the maximum record limit is reached, the data is truncated at the record limit. You receive the following message, which includes the maximum records value that has been exceeded.

The report headers in the output for a canned report, include report title, creation time, and the user associated with the session. Figure 5-1 shows the output for the MPLS VPN Association Report sent to a CSV file and displayed in a spreadsheet.

Figure 5-1 Example of an MPLS VPN Association Report

Process for SLA Provisioning

The following process summarizes the SLA provisioning process using the API.

1. Create and deploy the SLA probes. See the “Creating and Deploying SLA Probes” section.

2. Modify the SLA probe to enable or disable traps. Use ModifySLAProbe.xml.

3. Run an SLA collection task to start the collection of SLA data. See the “SLA Collection” section.

4. Gather the SLA data using the processes for SQL-Based Reports or Canned Reports. Prime Provisioning collects the data from the appropriate SLA databases. See the “SLA Reports” section.

5. Prime Provisioning returns the data across the client HTTP connection in an XML response or saves it to an output file. The output file can be in XML or CSV format. See the “Output for Reports” section.

6. This process is optional. Set up the API to receive event notifications for SLA probe and SLA collection changes (add/delete/modify instances). See the “Event Notifications” section.

SLA Probes

SLA probes can be configured on Cisco IOS devices. The probes store the measurement parameters at a certain frequency (for example, every 5 minutes) in the IOS buffer. An SLA collection server retrieves the measurement data from the device buffer at hour intervals and stores it in the Prime Provisioning database. There is one database for each collection server.

Using the Prime Provisioning API, you can create, delete, or view an SLA probe. You can modify a probe, but only to change the value of the EnableProbe or EnableTraps attributes (true/false).

Prime Provisioning supports creating probes from the following devices:

• From any SA Agent device
• From MPLS CPE
• From MPLS PE or MVRF-CE

To retrieve the measurement data from the database, use an SLA report. See the “SLA Reports” section for more information.

Creating and Deploying SLA Probes

To create an SLA probe from any SA Agent device, specify the common probe parameters, source devices, destination devices (where applicable), and protocol (ProbeType).

To create an SLA probe from an MPLS CPE, PE, or MVRF-CE, you must also specify a VPN. For MPLS PEs and MPLS MVRF-CEs, a VRF is also required.

Table 5-2 shows the operation, classNames, and child attributes to specify to create and deploy an SLA probe.

See the following example:

Common Probe Parameters

Table 5-3 describes the common probe parameters.

Probe Types

Prime Provisioning uses the ProbeType to specify the protocol of the traffic to monitor. The following protocols are available when you create an SLA probe from all devices only if destination devices are available:

• Internet Control Message Protocol Echo (ICMP Echo)
• Transmission Control Protocol Connect (TCP Connect)
• User Datagram Protocol Echo (UDP Echo)
• Jitter (voice jitter)

The following protocols are available when you create an SLA probe from all devices except MPLS PE:

• TCP Connect
• File Transfer Protocol (FTP)
• Domain Name System (DNS)
• Hyper text Transfer Protocol (HTTP)
• Dynamic Host Configuration Protocol (DHCP)

Table 5-4 describes the required attributes for each probe type (protocol).

Viewing SLA Probes

To view an SLA probe, use enumerateInstances, specify the probe type (for example, EchoProbe, JitterProbe, HTTPProbe), and enter a unique identifier, such as LocatorID.

Note The LocatorID can also be used to retrieve, modify, and delete a specific probe.

To view probes for a specific device, use SrcDevice or DestDevice as the unique identifier. See the following example:

SLA Reports

SLA reports gather information from the various SLA tables in the SLA database. SLA data is derived at specific intervals from the SLA repository. The information gathered in SLA reports depends on the probes that have been set for collection of information.

SLA reports can be created using execQuery or execReport.

• execQuery retrieves raw data from the main Prime Provisioning database or the SLA database. See the “SQL-Based Reports” section for more information.
• execReport for SLA, generates SLA reports based solely on data from the SLA tables in the SLA database.

Prime Provisioning supports the following report types:

• SLASummaryReport
• SLAHTTPReport
• SLAJitterReport
• SLASummaryCoSReport
• SLAHTTPCoSReport
• SLAJitterCoSReport

For the Summary, HTTP, and Jitter reports, you filter the SLA probe by DSCP and or IP precedence value. For the Summary CoS, HTTP CoS, and Jitter CoS reports, you specify the TOS type for the whole report.

To define the conditions for the SLA report, use the following required attributes:

• ValueDisplayed—See Table 5-5 for a complete list of options for each report type.
• Timeline and TimeGranularity—All, Yearly, Monthly, or Daily, Hourly.
• AggregateBy—All, Customer, Provider, VPN, Source_Router, or Probe.

The following filters are also available for SLA reports:

– Organization

– Provider

– VPN

– SrcDevice

– DestDevice

– Probes

– TOS

– DSCP

See the following example:

The output of an SLA report can an XML response or saved to a file. An output file can be in XML or CSV format. See the “Output for Reports” section for more information.