Table Of Contents
SCA BB Service Configuration API Overview
Service Configurations
Information About The Service Configuration API
Information About The Service Configuration Management API
Information About The Service Configuration Editing API
Program Workflow Using the Service Configuration API
SCA BB Service Configuration API Overview
This chapter describes various terms and concepts that are utilized when working with the Cisco SCA BB Service Configuration API (Service Configuration API).
•
Service Configurations
• Information About The Service Configuration API
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 that together determine how the Cisco Service Control Application, 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 the Cisco Service Control Application for Broadband User Guide .
Information About The 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:
•The 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
Information About The Service Configuration Management API
• The Service Configuration Management API
• Service Configuration Management API Classes
The 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 configurations to a PQB files. PQB files created by the API 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 is performed by creating a connection from the API program to the SCE platform, and then applying 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 is performed by creating a connection from the API program to the SCE platform, and then transferring the configuration from the SCE platform over the connection.
•Export parts of the service configuration to CSV files—Export 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 the Cisco Service Control Application for Broadband User Guide. The CSV formats are described in the "CSV File Formats" chapter of the 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 the Cisco Service Control Application for Broadband User Guide . The CSV formats are described in the "CSV File Formats" chapter of the 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
Information About The Service Configuration Editing API
• The Service Configuration Editing API
• Service Configuration Editing API Data Types
The 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, for example, according to the 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 BW 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's guides (see the 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 the Cisco Service Control Application for Broadband Reference Guide ) or via SQL to the Cisco Service Control Management Suite Collection Manager database (see the Cisco Service Control Management Suite Collection Manager User Guide ).
Service Configuration Editing API Data Types
•The main data types for traffic classification settings are services, protocols, signatures, zones, and flavors.
•The main data types for traffic accounting and reporting are counter definitions and various RDR parameters.
•The main data types for traffic control are packages, rules, subscriber BW controllers and global BW 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 the 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 common workflow for an application that uses the Service Configuration API is:
DETAILED STEPS
Step 1 The application retrieves a service configuration from the SCE platform.
Step 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.
Step 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.
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.
Implementing these workflows using the Service Configuration API is demonstrated in Information About Programming with the SCA BB Service Configuration API.
