Getting Started

Table Of Contents

Getting Started

Restrictions for the SCMS SCE Subscriber API

Information About the SCMS SCE Subsriber API

Platforms

Package Content

How to Extract and Install the Package

Installing the Distribution on a UNIX Platform

Installing the Distribution on a Windows Platform

How to Setup the SCE Platform

Prerequisites

Configuring the SCE in a Pull Model

How to Configure the RDR Formatter

How to Configure the RDR Server

How to Configure the API Disconnection Timeout

Getting Started

This module discusses the platforms on which the SCE Subscriber API can be used, and how to install, compile, and start running it.

The SCMS SCE Subscriber API provides the ability to external applications (policy servers) to connect directly to the SCE for the purpose of subscriber provisioning.

Subscriber provisioning is a process of updating the Network IDs , Policy Profile and Quota characteristics of the subscriber using the Subscriber ID as the correlation. For more information about the characteristics of the subscriber in the Service Control Application for Broadband (SCA BB), see the Subscriber Characteristics section.

The API can be installed and used concurrently on several policy servers and each of them can perform different parts of the subscriber provisioning process as shown in the following diagram:

Figure 1-1 SCE Subscriber API Installed on Multiple Servers

The API uses the PRPC (Proprietary Remote Procedure Call) protocol as a transport for the connection to the SCE. The PRPC is a proprietary RPC protocol designed by Cisco.

Note The API provides a connection to one SCE platform for each API instance.

Restrictions for the SCMS SCE Subscriber API

Version 3.0.5 of the API is backward compatible with previous versions, but is not binary-compatible. You must recompile applications that use a previous version of the API in order to use the new version. Since the API is backward compatible, you do not need to make any changes to the application source code.

Note If you upgrade the SCE to version 3.0.5, you must upgrade the API to version 3.0.5 and recompile the application that uses it.

Information About the SCMS SCE Subsriber API

• Platforms

• Package Content

Platforms

The SCMS SCE Subscriber API is operable on any platform that supports Java version 1.4.

Package Content

For brevity, the installation directory sce-java-api-_<version>_<build-number>is referred to as <installdir>.

The <installdir>/javadoc folder contains the 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 for the API operation.

Table 1-1 Layout of Installation Directory

Path

Name

Description

<installdir>

README

API readme file

<installdir>/javadoc

index.html

Index of all API specifications

(API specification files, etc.)

API specification documents

<installdir>/lib

sceapi.jar

SCE Subscriber API executable

asn1rt.jar

Utility jar used by the API

log4j.jar

Utility jar used by the API

log4j.properties

Property file needed for the logging functionalities

jdmkrt.jar

Utility jar used by the API

How to Extract and Install the Package

The SCMS SCE Subscriber API distribution is part of the SCMS SM-LEG distribution file and is located in the sce_api directory.

The SCMS SCE Subscriber API is packaged in a UNIX tar file. You can extract the SCMS SCE Subscriber API using the UNIX tar utility of most Windows compression utilities.

• 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 SCMS SM-LEG distribution file and locate the SCE Subscriber API distribution tar sce-java-api-dist.tar.gz

Step 2 Unzip the distribution file

#>gunzip sce-java-api-dist.tar.gz
Step 3 Extract the SCE Subscriber API package tar

#>tar -xvf sce-java-api-dist.tar

Installing the Distribution on a Windows Platform

Step 1 Use a zip extractor (such as WinZip) to unzip the package.

How to Setup the SCE Platform

The following sections describe the configuration that is performed on the SCE platform to allow correct API functioning.

• Prerequisites

• Configuring the SCE in a Pull Model

• How to Configure the RDR Formatter

• How to Configure the RDR Server

• How to Configure the API Disconnection Timeout

Prerequisites

The API connects to the PRPC server on the SCE platform. The PRPC server is a server running a proprietary RPC protocol designed by Cisco. For more information, see the SCE User Guide .

Before using the API, ensure that:

•The SCE must be up and running, and reachable from the machine that hosts the API.

•The PRPC server on the SCE must be started.

Configuring the SCE in a Pull Model

To enable the SCE platform to issue a request for subscriber information when running in a Pull Model (see Pull Model ), configure the following using the SCE platform Command-Line Interface (CLI).

For more information about configuring the SCE platform, see the Cisco SCE 1000 2xGBE Installation and Configuration Guide or the Cisco SCE 2000 4xGBE Installation and Configuration Guide .

Step 1 Configure the subscriber templates

(config if)#>subscriber template import CSV file
For more information about the templates and the format of the CSV file, see the Cisco Service Control Application for Broadband User Guide .

Step 2 Configure the unmapped-subscriber groups ranges

a. Use the subscriber anonymous group import CLI to import anonymous groups from a file.

(config if)#>subscriber anonymous group import CSV file
b. Alternatively, use the subscriber anonymous group name CLI to manually define the anonymous group

(config if)#>subscriber anonymous group name NAMEIP-range IP RANGE
How to Configure the RDR Formatter

• 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 RDR formatter to issue quota-related indications, configure the RDR formatter on the SCE platform as follows.

Step 1 Use the RDR-formatter destination CLI.

#>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, use the following command.

Step 1 Use the RDR-formatter rdr-mapping CLI

#>RDR-formatter rdr-mapping tag-ID tag numbercategory-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, it should be enabled in the Cisco Service Control Application for Broadband GUI . See the Cisco Service Control Application for Broadband User Guide for configuration description.

How to Configure the RDR Server

To enable the API to receive Quota indications, the RDR server should be enabled and listening on the same port that is configured in the RDR formatter.

• 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, do the following.

Step 1 Use the show RDR-server CLI.

#>show RDR-serverRDR server is ONLINE RDR server port is 33001
Enabling the RDR Server

To enable the RDR server, do the following

Step 1 Use the configuration RDR-server CLI

#>configure(config)#>RDR-server Default RDR server port is 33001
Changing the RDR Server Port

To change the RDR server port, do the following.

Step 1 Use the RDR-server port CLI

#>configure(config)#>RDR-server port port
How to Configure the API Disconnection Timeout

The SCE platform allows setting the timeout for the API to reconnect to the SCE platform after it was disconnected. During this timeout, the SCE will not free the resources and no data will be lost. After the timeout has elapsed and the API did not reconnect, the SCE considers the API disconnected and frees all the resources. The default timeout value is 5 minutes.

• Configuring the API Disconnection Timeout

• Reset the Disconnection Timeout to the Default Value

• Viewing the Timeout Value

Configuring the API Disconnection Timeout

To configure the API disconnection timeout, do the following:

Step 1 Use the management-agent sce-api timeout CLI

(config)# management-agent sce-api timeout timeout-in-sec
Reset the Disconnection Timeout to the Default Value

To reset the API disconnection timeout to the default value, do the following:

Step 1 Use the default management-agent sce-api timeout CLI

(config)# default management-agent sce-api timeout
Viewing the Timeout Value

To view the timeout value, do the following:

Step 1 Use the show management-agent sce-api CLI

# show management-agent sce-api

Path	Name	Description
<installdir>
	README	API readme file
<installdir>/javadoc
	index.html	Index of all API specifications
	(API specification files, etc.)	API specification documents
<installdir>/lib
	sceapi.jar	SCE Subscriber API executable
	asn1rt.jar	Utility jar used by the API
	log4j.jar	Utility jar used by the API
	log4j.properties	Property file needed for the logging functionalities
	jdmkrt.jar	Utility jar used by the API