Cisco SCA BB Service Configuration API Programmer Guide, Release 4.1.x
Bias-Free Language
The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
- Updated:
- June 9, 2011
Chapter: SCA BB Service Configuration API Overview
SCA BB Service Configuration API Overview
Introduction
This chapter describes various terms and concepts that are used when working with the Cisco SCA BB Service Configuration API.
This chapter consists of these sections:
Service Configurations
One of the fundamental entities in the Cisco Service Control solution is a service configuration. A Service Configuration is a collection of configuration parameters. These parameters together determine how the Cisco SCA, which runs on the Cisco 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 the 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. Cisco SCA BB is a GUI tool that lets you edit every aspect of the configuration and apply changes to the SCE platform.
The Service Configuration API enables external applications to change the policy that SCE platform enforces, 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. For example, 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. For example, changing a classification criterion or adding a policy rule.
This section contains these topics:
•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 (created by the API and 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 comma-separated values (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.
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—Provides the connection to the SCE platform.
•ImportExportApi—Provides methods for saving service configurations to and reading service configurations from PQB files. This API also provides methods 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—Determines how the SCA performs classification, accounting and reporting, and control over network. Objects of this class are basically containers of configuration parameters.
Service Configuration Editing API
The Service Configuration Editing API can be used to perform the following tasks:
•Inspecting a service configuration—Inspects a configuration that is retrieved from an SCE platform to determine, for example, which services and subscriber packages it contains. This API can be used for comparing two configurations.
•Configuring criteria for traffic classification—Determines 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—Determines how network traffic is controlled by using rules for each service and for each subscriber package, elaborate bandwidth control hierarchy, and quota management models. The API can be used to change these settings, thus 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 by 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 by using this API. You can monitor counters via SNMP to the SCE platform or via SQL to the Cisco Service Control Management Suite Collection Manager database. For details on monitoring via SNMP, see the "SCA BB Proprietary MIB Reference" chapter of Cisco Service Control Application for Broadband Reference Guide. For details on monitoring via SQL, see the 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 settings are counter definitions and various Raw Data Records (RDR) parameters.
•Traffic control settings 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. See the "Traffic Processing Overview" chapter of Cisco Service Control Application for Broadband User Guide.
Use the SCA BB Console, which uses Service Configuration Editing API, to get familiar with these configuration objects and to understand the capabilities of 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.
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.
Another common workflow uses 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 response to some external trigger or at specified times.
Feedback