SCA BB Service Configuration API Overview
Revised: November 8, 2010, OL-21067-02
This chapter describes various terms and concepts that are utilized when working with the Cisco SCA BB Service Configuration API:
•Service Configuration API
One of the fundamental entities in the Cisco Service Control solution is a service configuration. A Service Configuration is a collection of configuration parameters that together determines how the Cisco Service Control Application (SCA), which runs on the Service Control Engine (SCE) platform, performs classification, accounting and reporting, and control of network traffic.
By editing a service configuration and applying it to the SCE platform, you can change the way traffic is classified and enforce different policies.
For more information about service configurations and traffic processing, see Cisco Service Control Application for Broadband User Guide.
Service Configuration API
Usually, editing and managing service configurations is done manually in the Cisco SCA BB Console, which is a GUI tool that lets you edit every aspect of the configuration and apply changes to the SCE platform.
The Service Configuration API provides the ability for external applications to change the policy that is enforced by an SCE platform, by programmatically editing service configurations and applying these configurations to SCE platforms.
The Service Configuration API has two parts, each dealing with a different type of task:
•Service Configuration Management API—Handles the tasks that are performed on a service configuration as a whole, such as applying a configuration to an SCE platform, and saving the configuration to a file.
•Service Configuration Editing API—Handles changes to a single service configuration, such as changing a classification criterion or adding a policy rule.
•Service Configuration Management API
•Service Configuration Editing API
•Program Workflow Using the Service Configuration API
Service Configuration Management API
The Service Configuration Management API can be used to perform the following tasks:
•Create a new service configuration—Creates a new service configuration object, with default configuration values. This configuration can be edited, and then applied, to an SCE platform or saved to a file.
•Save a service configuration to a file—Saves a service configuration to a PQB file. PQB files created by the API that can be edited in the SCA BB Console, and vice versa.
•Read a service configuration from a file—Loads a PQB file, before applying it to an SCE platform or for editing purposes.
•Apply a service configuration to an SCE platform—Activates a service configuration on an SCE platform (the main operation of the API). This task creates a connection from the API program to the SCE platform and then applies the service configuration to the SCE platform over the connection.
•Retrieve a service configuration from an SCE platform—Gets the currently applied service configuration from the SCE platform. This task creates a connection from the API program to the SCE platform and then copies the configuration from the SCE platform over the connection.
•Export parts of the service configuration to CSV files—Exports parts of a service configuration, such as zones, flavors, and protocols, to a CSV file. CSV files can be manipulated manually or by some external system, and then imported back into service configurations.
•Import parts of the service configuration from CSV files—Imports parts of a service configuration from a CSV file to an open service configuration. A program can create such CSV files automatically, import them into a service configuration, and then apply the updated configuration to the SCE platform. Those parts of service configurations that can be imported to and exported from CSV files are described in the "Using the Service Configuration Editor" chapter of Cisco Service Control Application for Broadband User Guide. The CSV formats are described in the "CSV File Formats" chapter of Cisco Service Control Application for Broadband Reference Guide.
Those parts of service configurations that can be imported to and exported from CSV files are described in the "Using the Service Configuration Editor" chapter of Cisco Service Control Application for Broadband User Guide. The CSV formats are described in the "CSV File Formats" chapter of Cisco Service Control Application for Broadband Reference Guide.
Service Configuration Management API Classes
The main classes of the Service Configuration Management API are:
•SCABB—Provides methods for connecting to the SCE platform, to be used for apply and retrieve operations.
•ConnectionApi—The connection to the SCE platform.
•ImportExportApi—Provides methods for saving service configurations to and reading service configurations from PQB files, and for importing and exporting parts of service configurations to and from CSV files.
•ServiceConfigApi—Provides the methods for creating a new service configuration, and for applying service configurations to and retrieving service configurations from SCE platforms.
•ServiceConfig—Objects of this class are containers of configuration parameters that, when applied to the SCE platform, determine how the service control application performs classification, accounting and reporting, and control over network traffic.
Service Configuration Editing API
The Service Configuration Editing API can be used to perform the following tasks:
•Inspecting a service configuration—The API can inspect a configuration that is retrieved from an SCE platform to determine, for example, which services and subscriber packages it contains. This can be used for comparing two configurations.
•Configuring criteria for traffic classification—A service configuration can determine how traffic is classified according to various criteria such as URL of HTTP transactions. For example, the API can be used to automatically update lists of URLs that deny access to certain websites.
•Configuring various aspects of traffic control—The service configuration determines how network traffic is controlled using rules per service and per subscriber package, elaborate bandwidth control hierarchy, and quota management models. The API can be used to change these settings, thereby changing the policy enforced by the SCE platform in an automatic manner, for example, as a response to some external trigger or at specified time intervals.
Note Provisioning policy to subscribers cannot be performed using this API. Use the Subscriber APIs described in the SM API programmer guides (see Cisco SCMS SM Java API Programmer Guide or the Cisco SCMS SM C/C++ API Programmer Guide).
Note Monitoring counters cannot be performed using this API. Monitor counters via SNMP to the SCE platform (see the "SCA BB Proprietary MIB Reference" chapter of Cisco Service Control Application for Broadband Reference Guide) or via SQL to the Cisco Service Control Management Suite Collection Manager database (see Cisco Service Control Management Suite Collection Manager User Guide).
Service Configuration Editing API Data Types
The service configuration editing API data types for:
•Traffic classification settings are services, protocols, signatures, zones, and flavors.
•Traffic accounting and reporting are counter definitions and various Raw Data Records (RDR) parameters.
•Traffic control are packages, rules, subscriber bandwidth controllers and global bandwidth controllers.
An explanation of the objects (service configuration entities) that make up a service configuration is beyond the scope of this document: refer to the "Traffic Processing Overview" chapter of Cisco Service Control Application for Broadband User Guide. Using the SCA BB Console (which uses the Service Configuration Editing API) is a good way to become familiar with these configuration objects, and to get an idea of what you can do with the API.
Program Workflow Using the Service Configuration API
A typical workflow for an application that uses the Service Configuration API is:
1. The application retrieves a service configuration from the SCE platform.
2. The application modifies the service configuration.
For example, the application may import zone settings from a CSV file (a zone is a list of network-side IP addresses that serve as a classification criterion). After a zone is defined in the service configuration, you can create a rule to control all network traffic going to that zone.
For code example, see the "Updating Zones Automatically" section on page 3-35.
3. The application applies the modified service configuration to the SCE platform so that classification and enforcement can take place according to the updated configuration.
For code example, see the "Applying a Service Configuration" section on page 3-33.
Another common workflow makes use of a set of predefined service configurations (created manually in the SCA BB Console). In this workflow, the application uses the API to apply each service configuration to the SCE platform, either as a response to some external trigger or at specified times.