Concepts and Terms
Revised: November 8, 2010, OL-21083-02
This chapter describes various terms and concepts that are used when working with the Service Control Management Suite (SCMS) Service Control Engine (SCE) Subscriber Application Programming Interface (API).
•Information About Subscriber Integration Modes
A subscriber is one of the fundamental entities in the Service Control Application for Broadband
(SCA BB) solution. A subscriber is used by the SCA BB solution for individually enforcing, accounting, and monitoring a service configuration. For more information about the format and usage of the subscriber characteristics, see Chapter 4 "Getting Familiar with the Application Programming Interface Data Types." The following sections briefly describe the characteristics of the subscriber in the SCA BB:
•Anonymous Subscriber ID
Subscriber ID is a unique identifier, for example, a user name, International Mobile Subscriber Identity (IMSI), or other code that uniquely identifies a subscriber.
Anonymous Subscriber ID
When working in the Pull mode integration, the SCE assigns each unknown subscriber IP address with a temporary, anonymous Subscriber ID, until it receives the real Subscriber ID from the Policy Server.
For more information on the Pull mode integration, see the "Information About Subscriber Integration Modes" section.
The SCE correlates a certain traffic flow to a subscriber by mapping a network identifier, for example, IP address, IP range, or VLAN, to the subscriber entity.
A Policy Profile includes a set of parameters used by the SCA BB solution to define what policy is enforced on the subscriber.
A quota includes the quota-bucket values of the service quota or quotas available for the usage of the subscriber.
Extended Attributes represents the data structure of the extended attributes associated with the subscriber.
Information About Subscriber Integration Modes
The following terms describe two modes of a dynamic subscriber integration that the SCE platform supports.
In Push mode integration, an external server introduces (pushes) the subscribers to the SCE platform as shown in Figure 2-1. This introduction (push) is performed whenever a new subscriber logs in to the network or the external server presumes to know all subscribers and introduces them to the SCE box when they connect.
Figure 2-1 Push Mode Schematic
In Pull mode integration, the SCE platform requests subscriber data from the external entity when it encounters traffic of an unknown subscriber, known as an anonymous subscriber as shown in Figure 2-2. The external entity retrieves the required subscriber information and sends it back to the SCE platform.
Figure 2-2 Pull Mode Schematic
The SCE Subscriber API is implemented using a nonblocking mode. Nonblocking methods return immediately, even before the completion of a subscriber provisioning operation. The Nonblocking mode method is advantageous when the operation is lengthy and involves I/O. Performing the operation in a separate thread allows the caller to continue doing other tasks and it improves overall system performance.
The operation results are either returned to an observer object (listener) or not returned at all.
The API supports retrieval of operation results using an operation result handler described in the "Information About Result Handling" section.
Figure 2-3 illustrates the Nonblocking mode method during a subscriber provisioning operation:
Figure 2-3 Nonblocking Mode
Operation results can be used for operation result error logging or for inspection of the parameters used by the operation.
The API provides the user with the ability to receive an indication when certain events occur on the SCE platform as shown in Figure 2-4. The API dispatches the indications received from the SCE to the interested entities, called listeners, by activating the relevant listeners callback methods. The indications are separated into several logical groups when only one listener can be defined for each group of indications.
Figure 2-4 Indication Listeners
To receive certain indications, you need to register a listener to the API that implements the required callback functions. After the listener is registered, the API can dispatch the required indications to the listener. The SCMS SCE Subscriber API provides three types of indications when separate listeners are registered to the following types of the indications:
For more information about listener indications, see Chapter 3 "Application Programming Interface Events."
The following topologies are recommended to use with the SCMS SCE Subscriber API:
•One policy server (or one 2-node cluster) that is responsible for all aspects of the subscriber provisioning process as shown in Figure 2-5.
Figure 2-5 Supported Topologies - One Policy Server
•Three policy servers (or three 2-node clusters)—Every server is responsible for a different aspect of the subscriber provisioning process as shown in Figure 2-6.
Figure 2-6 Supported Topologies - Three Policy Servers
•Two policy servers (or two 2-node clusters) when one of the servers is responsible for two aspects of the subscriber provisioning and the other server is responsible for one aspect only (any combination is allowed) as shown in Figure 2-7.
Figure 2-7 Supported Topologies - Two Policy Servers
•Dynamic Host Configuration Protocol (DHCP) Lease Query Login Event Generator (LEG), which is responsible for mapping a Network ID to a Subscriber ID, with one or more policy servers as shown in Figure 2-7. Figure 2-8 shows the DHCP Lease Query LEG.
Figure 2-8 Supported Topologies - DHCP Lease Query LEG
•SCMS SM, which is responsible for mapping Network ID to Subscriber ID, with one or more policy servers as shown in Figure 2-9. The number of policy servers depends on whether the SM is used for policy profile provisioning in addition to the network ID:
Figure 2-9 Supported Topologies - SM
The API itself does not limit the use of any topology; however, the SCE platform does not correlate between all the entries (Policy Servers) that perform subscriber provisioning. Therefore you should be
careful when using more than one Policy Server for the
same provisioning purpose
(for example Network ID/Subscriber ID correlation). If you are not careful when using more than one Policy Server, the SCE platform may receive different information for the same subscriber from the two policy servers responsible for the same aspect of the subscriber provisioning. This may cause a loss of synchronization with at least one policy server. For example, using two policy servers that are responsible for providing Subscriber ID/Network ID correlation for the same subscriber produces a situation in which the SCE is always synchronized with the policy server that performed the last update for this subscriber.
The API supports an unlimited number (limited by the available memory) of threads calling its methods simultaneously.
Note In a multithreaded scenario, the order of invocation is guaranteed. The API performs operations in the same chronological order that they were called.
The API supports autoreconnection to the SCE in case of connection failure. When this option is activated, the API can determine when the connection to the SCE is lost. When the connection is lost, the API activates a reconnection task that tries to reconnect to the SCE again in a configurable interval time until reconnection is successful.
The SCMS SCE Subscriber API is implemented as a reliable API. The API ensures that no requests to the SCE are lost and no indication from the SCE is lost. The API maintains an internal storage for all API requests that were sent to the SCE. Only after receiving an acknowledgement from the SCE that the request was handled does it consider the request as committed and the API can remove the request from its internal storage. If a connection failure occurs between the API and the SCE, the API accumulates all requests in its internal storage until the connection to the SCE is reestablished. On reconnection, the API resends all noncommitted requests to the SCE, ensuring that no requests are lost.
Note The order of resending requests is guaranteed. The API resends the requests in the same chronological order that they were called.
The API provides high-availability support. It assumes that the high-availability scheme of the policy server is a two-node cluster type in which only one server is active at any given time. The other server, in standby, is not connected to the SCE. For more information, see the "Implementing High-Availability" section.
The SCE and Policy Server must be kept synchronized concerning the subscribers for which the SCE is handling their internal parameters. Otherwise, the SCE might confuse the traffic of one subscriber with that of another, or the Service Level Agreement (SLA) of the subscriber will not be enforced because of a change in the policy that did not reach the SCE. For more information, see the "Information About SCE-API Synchronization" section.
When implementing the code that integrates the API with your application, you should consider the following practical tips:
•Connect once to the SCE and maintain an open API connection to the SCE at all times, using the API many times. Establishing a connection is a timely procedure, which allocates resources on the SCE side and the API client side.
•Share the API connection between your threads—it is better to have one connection per Policy Server. Multiple connections require more resources on the SCE and client side.
•Do not implement synchronization of the calls to the API. The client automatically synchronizes calls to the API.
•If the Policy Server application has bursts of logon operations, enlarge the internal buffer size accordingly to hold these bursts (Nonblocking flavor).
•During the integration, use the logging capabilities that are described in the "SCE Logging" section and in the "API Client Logging" section to view the API operations in the SCEs client logs and to troubleshoot problems during the integration, if any.
•Use the debug mode for the Policy Server application that logs/prints the return values of the operations.
•Use the automatic reconnect feature to improve the resiliency of the connection to the SCE.