Cisco SCMS SCE Subscriber API Programmer Guide, Release 4.0.x

Getting Started

Introduction

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.

Restrictions for the Cisco SCE Subscriber API

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.

Cisco SCE Subscriber API

This section consists of the following subsections:

•Platforms

•Package Content

Platforms

The Cisco SCE Subscriber API operates on any platform that supports Java Version 5.0.

Package Content

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.

Extracting and Installing the Package

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

Installing the Distribution on a UNIX 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

Installing the Distribution on a Windows Platform

To install the distribution, use a zip extractor (such as WinZip) to unzip the package.

The Cisco SCE Platform Setup

The following sections describe how to configure the Cisco SCE platform so that the API operates correctly:

•Prerequisites

•Configuring Cisco SCE in Pull Mode

•Configuring the RDR Formatter

•Configuring the RDR Server

•Configuring Cisco SCE for Quota Management Provisioning

•Configuring the API Disconnection Timeout

Prerequisites

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.

Configuring Cisco SCE in Pull Mode

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 

Configuring the RDR Formatter

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

Configuring the RDR Formatter to Issue Quota-Related Indications

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

Mapping the Quota RDR Tags to a Different Category

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.

Configuring the RDR Server

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

•Enabling the RDR Server

•Changing the RDR Server Port

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

Enabling the RDR Server

To enable the RDR server, enter the RDR-server CLI command as follows:

#> configure

(config)#> RDR-server

Default RDR server port is 33001

Changing the RDR Server Port

To change the RDR server port, enter the RDR-server port CLI command as follows:

#> configure

(config)#> RDR-server port port

Configuring Cisco SCE for Quota Management Provisioning

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.

Configuring the API Disconnection Timeout

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

•Viewing the Timeout Value

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

Viewing the Timeout Value

To view the timeout value, enter the show management-agent sce-api CLI command as follows:

#> show management-agent sce-api