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.
This chapter identifies the platforms on which you can run the Cisco Service Control Engine (SCE) Subscriber application programming interface (API). The chapter also describes how to install, compile, and start running the API.
The Cisco SCE Subscriber API enables you to connect policy servers (external applications) to a Cisco SCE so that you can provision subscribers.
Subscriber provisioning entails updating the Network IDs, Policy Profile, and Quota and correlating these characteristics to a Subscriber ID. For more information about the characteristics of a subscriber in the Cisco Service Control Application for Broadband (Cisco SCA BB), see the "Subscriber Characteristics" section.
You can install and run the API on several policy servers concurrently. Each policy server can perform different parts of the subscriber provisioning process as shown in Figure 1-1.
Figure 1-1 Cisco SCE Subscriber API Installed on Multiple Servers
The API uses the Proprietary Remote Procedure Call (PRPC) protocol to transport the connection to the Cisco SCE. The PRPC is a proprietary remote procedure call protocol designed by Cisco.
Note The API provides a connection to one Cisco SCE platform for each API instance.
Version 3.0.5 of the API is backward compatible with previous versions, but is not binary compatible. Recompile applications that use a previous version of the API to use the new version. Because the API is backward compatible, you do not need to change the application source code.
Note If you upgrade Cisco SCE to Release 3.0.5, upgrade the API to Version 3.0.5 and recompile the application that uses it.
This section consists of the following subsections:
The Cisco SCE Subscriber API operates on any platform that supports Java Version 5.0.
For brevity, the installation directory, sce-java-api-_<version>_<build-number>, is referred to as <installdir>.
The <installdir>/javadoc folder contains the Cisco SCE Subscriber API JAVADOC documentation.
The <installdir>/lib folder contains the sceapi.jar file, which is the API executable. It also contains additional JAR files necessary to operate the API.
Table 1-1 provides the layout of the installation directory.
The Cisco SCE Subscriber API distribution is part of the Cisco Service Control SM login event generator (LEG) distribution file and is located in the sce_api directory.
The Cisco SCE Subscriber API is packaged in a UNIX tar file. Use the UNIX tar utility to extract the Cisco SCE Subscriber API. The API is compiled with support from Log4J Version 1.2.
This section consists of the following subsections:
•Installing the Distribution on a UNIX Platform
•Installing the Distribution on a Windows Platform
Step 1 Extract the Cisco SM-LEG distribution file and locate the Cisco SCE Subscriber API distribution tar, sce-java-api-dist.tar.gz.
Step 2 Unzip the distribution file by using the following command:
#> gunzip sce-java-api-dist.tar.gz
Step 3 Extract the Cisco SCE Subscriber API package tar file by using the following command:
#> tar -xvf sce-java-api-dist.tar
To install the distribution, use a zip extractor (such as WinZip) to unzip the package.
The following sections describe how to configure the Cisco SCE platform so that the API operates correctly:
•Configuring Cisco SCE in Pull Mode
•Configuring the RDR Formatter
•Configuring Cisco SCE for Quota Management Provisioning
•Configuring the API Disconnection Timeout
The API connects to the PRPC server on the Cisco SCE platform. The PRPC server runs a PRPC protocol designed by Cisco.
Before using the API, ensure that the following conditions are met:
•The Cisco SCE is active, running, and reachable from the machine that hosts the API.
•The PRPC server on the Cisco SCE is started.
To enable the Cisco SCE platform, running in Pull Mode, to issue a request for subscriber information, complete the following configuration steps using the Cisco SCE platform CLI. See the "Pull Mode" section.
For more information about configuring the Cisco SCE platform, see the Cisco SCE 1000 2xGBE Installation and Configuration Guide or the Cisco SCE 2000 Installation and Configuration Guide.
Step 1 Configure the subscriber templates. For example,
(config if)#> subscriber template import CSV file
For more information about the templates and the format of the comma-separated value (CSV) file, see the Cisco Service Control Application for Broadband User Guide.
Step 2 Configure the ranges for unmapped subscriber groups.
•Enter the subscriber anonymous group import CLI command to import anonymous groups from a file.
(config if)#> subscriber anonymous group import CSV file
•Alternatively, enter subscriber anonymous group name the CLI command to define the anonymous group.
(config if)#> subscriber anonymous group name NAME IP-range IP RANGE
This section consists of the following subsections:
•Configuring the RDR Formatter to Issue Quota-Related Indications
•Mapping the Quota RDR Tags to a Different Category
To enable the Raw Data Record (RDR) formatter to issue quota-related indications, configure the RDR formatter on the Cisco SCE platform. Enter the RDR-formatter destination CLI command as follows:
#> RDR-formatter destination 127.0.0.1 port 33001 category number 4 priority 100
By default, Quota RDR tags are mapped to category 4. If another category is required, enter the RDR-formatter rdr-mapping CLI command as follows:
#> RDR-formatter rdr-mapping tag-ID tag number category-number number
Note For Quota RDR tag IDs, see the Cisco Service Control Application for Broadband User Guide.
To enable the application to issue quota-related indications, enabled it with the Cisco Service Control Application for Broadband GUI. See the Cisco Service Control Application for Broadband User Guide for configuration description.
To enable the API to receive quota indications, enable the RDR server to listen on the same port that is configured in the RDR formatter.
This section consists of the following subsections:
•Verifying the RDR Server Configuration
To verify the RDR server configuration, enter the show RDR-server CLI command as follows:
#> show RDR-server
RDR server is ONLINE
RDR server port is 33001
To enable the RDR server, enter the RDR-server CLI command as follows:
#> configure
(config)#> RDR-server
Default RDR server port is 33001
To change the RDR server port, enter the RDR-server port CLI command as follows:
#> configure
(config)#> RDR-server port port
To configure the Cisco SCE to provision the quota management, complete the following steps:
Step 1 Service the RDR formatter.
SCE8000(config)#> service RDR-formatter
Step 2 Enable, throught PQB file or CLU, the Quota RDRs in service configuration file to get quota indications.
SCE8000(config if)#> tunable GT_REP_QP_RemainQuota_Enable value true
SCE8000(config if)#> tunable GT_REP_QP_QuotaBreach_Enable value true
SCE8000(config if)#> tunable GT_REP_QP_ThresholdBreach_Enable value true
SCE8000(config if)#> tunable GT_REP_QP_RemainQuota_MaxFrequency value 1000
SCE8000(config if)#> tunable GT_REP_QP_RemainQuota_Rate value 60
Step 3 Set the quota management mode to External in Cisco SCA BB console.
You can set the timeout duration for the API to wait before it reconnects to the Cisco SCE platform following a disconnection. During this timeout, the Cisco SCE does not free the resources and no data is lost. After the timeout elapses and the API does not reconnect, the Cisco SCE considers the API disconnected and frees all resources. The default timeout value is 5 minutes.
To configure the API disconnection timeout, enter the
management-agent sce-api timeout CLI command as follows:
(config)# management-agent sce-api timeout timeout-in-sec
This section consists of the following subsections:
•Resetting the Disconnection Timeout to the Default Value
To reset the API disconnection timeout to the default value, enter the default management-agent sce-api timeout CLI command as follows:
(config)# default management-agent sce-api timeout
To view the timeout value, enter the show management-agent sce-api CLI command as follows:
#> show management-agent sce-api