Cisco SCMS SCE Subscriber API Programmer Guide, Release 3.5.5
Application Programming Interface Events
Downloads: This chapterpdf (PDF - 405.0KB) The complete bookPDF (PDF - 1.71MB) | Feedback

Application Programming Interface Events

Table Of Contents

Application Programming Interface Events

Introduction

Information About API Events

Information About Network ID Management Events

Information About Login Events

Logout Events

Network ID Update Event

Information About Policy Profile Management Events

Profile Update Event

Information About Quota Management Events

Quota Update Event

Get Quota Status Event

Quota Status Event

Quota Below Threshold Event

Quota Depleted Event

Quota State Restore Event

Information About SCE Synchronization Procedure Events

Start Synchronization Event

End Synchronization Event

Get Subscribers Events


Application Programming Interface Events


Revised: July 28, 2009, OL-8236-08

Introduction

This chapter describes various events accessed by the Service Control Management Suite (SCMS) Service Control Engine (SCE) Subscriber Application Programming Interface (API).

Information About API Events

The API accesses a set of 'events' that are a pre-defined set of messages passed back and forth between the Policy Server and the SCE platform:

Figure 3-1 API Events Overview

API Events Overview

Every message can be assigned a type according to the purpose of the message:

Request—Requests information or an action to be performed. A request is not necessarily followed by a response.

Response—Answers a previous request

Indication—Indicates the other side that an event has occurred

Most of the events may be used for both push and pull models. See Information About Subscriber Integration Models, page 2-3.

The events may be divided into the following Subscriber Provisioning process groups:

Network ID management events—Includes events relating to the modification of the subscriber Network ID mapping

Policy Profile management events—Includes events relating to modification of the subscriber Policy Profile parameters

Quota management events—Includes events relating to the management of subscriber quota

SCE Synchronization management events—Includes events relating to the management of the SCE synchronization process

You can perform bulk operations, which bundle many triggers for the same event on many subscribers to one global event.

The following sections provide a general description of each type of event.

Information About Network ID Management Events

Information About Policy Profile Management Events

Information About Quota Management Events

Information About SCE Synchronization Procedure Events

Information About Network ID Management Events

Information About Login Events

Logout Events

Network ID Update Event

Information About Login Events

Login events occur when the subscriber connects to the network and vary for pull and push models.

Push Model

Pull Model

Push Model

The push integration model assumes that the Policy Server triggers the subscriber introduction to the SCE. For example, the server receives a subscriber login indication from an external entity such as AAA (Authorization, Authentication, and Accounting), extracts the required subscriber attributes, and "pushes" the information to the SCE platform:

Figure 3-2 Login Events - Push Model

Login Events - Push Model

The subscriber login operation may either cause the creation of a new subscriber record in the SCE or update an existing subscriber. For example, for cable modem networks the subscriber is a cable modem and the CPEs connected to this cable modem are configured as a list of IP addresses (potentially ranges). In this case, the login of the new CPE connected to the same modem causes the CPE IP address to be added to the subscriber's Network ID list.

Pull Model

The pull integration model assumes that the SCE discovers a new subscriber from the incoming data traffic. The new subscriber is entered in the system as an anonymous subscriber and is assigned one of the default policies. The SCE initiates a request to the external system (a login-pull request) that may either provide the subscriber login information (a login-pull reply) or is omitted if no information exists for this IP. The login information provided to the SCE replaces the anonymous subscriber with the actual subscriber and enforces the correct policy.

If the external system rejects the login and the traffic keeps coming from the anonymous subscriber, the pull request will be retried.

Figure 3-3 Login Events - Pull Model

Login Events - Pull Model


Note Despite being classified as "Network-ID Management Event", LOGIN-REQUEST event and LOGIN-PULL-RESPONSE event are optimized to allow sending all subscriber information to the SCE. It is recommended to use these events for Policy Profile and Quota updates when a single Policy Server performs all parts of the subscriber provisioning. For multiple Policy Servers topologies, use separate events for updating Policy Profile and Quota information described in the following sections. For more information about topologies, see the Supported Topologies, page 2-5.


Logout Events

The logout event indicates that the subscriber no longer uses a certain network ID. A logout event is not necessarily followed by the removal of the subscriber record from the SCE. For example, in cable modem networks, when there are more than one CPE connected to the same modem, the logout of one CPE may not lead to the removal of a subscriber if another CPE remains connected. The actual removal of the subscriber occurs when all of the CPEs (Subscriber's network-IDs) are disconnected.

Figure 3-4 Logout Request Event

Logout Request Event

The logout event in the pull model may occur, for example, when the SCE identifies that the subscriber is not active for a specific time interval. The SCE "logs out" the subscriber and sends a LOGOUT-INDICATION event.

Figure 3-5 Logout Indication Event

Logout Indication Event

The LOGOUT-INDICATION event may also follow the Logout operation. This occurs once a subscriber is actually removed; for example, when no more valid network mappings (IP) are associated with this subscriber.

Figure 3-6 Logout Request Event

Logout Request Event

Network ID Update Event

This event is a REQUEST from the Policy Server to the SCE to update the network ID of the subscriber that already exists in the SCE platform. This event does not require any RESPONSE.

Figure 3-7 Network ID Update Event

Network ID Update Event

Information About Policy Profile Management Events

Profile Update Event

This event is a REQUEST from the Policy Server to the SCE to update the policy profile of the subscriber that already exists in the SCE platform. This event does not require any RESPONSE.

Figure 3-8 Profile Update Event

Profile Update Event


Note As described above, the LOGIN-REQUEST event and LOGIN-PULL-RESPONSE event can also update the policy profile.


Information About Quota Management Events

Quota Update Event

Get Quota Status Event

Quota Status Event

Quota Below Threshold Event

Quota Depleted Event

Quota State Restore Event

Quota Update Event

The Quota Update Event is a REQUEST from the Policy Server to the SCE to update the quota of the subscriber that already exists in the SCE platform. This event does not require any RESPONSE event.

Figure 3-9 Quota Update Event

Quota Update Event


Note As described above, the LOGIN-REQUEST event and LOGIN-PULL-RESPONSE event can also update the quota.


Get Quota Status Event

The Get Quota Status Event is a REQUEST from the Policy Server to the SCE to report the quota information of the subscriber that already exists in the SCE platform. A QUOTA-STATUS-INDICATION event follows this event.

Figure 3-10 Get Quota Status Event

Get Quota Status Event


Note A QUOTA-STATUS-INDICATION event may be issued periodically by the SCE without a specific request from the Policy Server. See Quota Status Event.


Quota Status Event

The SCE uses the Quota Status INDICATION event to notify the Policy Server about the remaining quota. This event is invoked periodically in a preconfigured time interval.

Figure 3-11 Quota Status Event

Quota Status Event

Quota Below Threshold Event

The SCE uses the Quota Below Threshold INDICATION event to notify the Policy Server that the remaining quota for certain services of the specific subscriber is below the preconfigured threshold. An UPDATE-QUOTA-REQUEST event from the Policy Server to the SCE may follow this event, but it is not mandatory.

Figure 3-12 Quota Below Threshold Event

Quota Below Threshold Event

Quota Depleted Event

The SCE uses the Quota Depleted INDICATION event to notify the Policy Server that the quota for certain services of the specific subscriber is depleted. An UPDATE-QUOTA-REQUEST event from the Policy Server to the SCE may follow this event.

Figure 3-13 Quota Depleted Event

Quota Depleted Event

Quota State Restore Event

The Quota State Restore Event is an INDICATION from the SCE to the Policy Server to restore the quota of the subscriber that exists in the SCE platform. This event is invoked immediately after a subscriber is logged in to the SCE. A Quota Update event from the Policy Server may follow this event.

Figure 3-14 Quota State Restore Event

Quota State Restore Event

Information About SCE Synchronization Procedure Events

Start Synchronization Event

End Synchronization Event

Get Subscribers Events

Start Synchronization Event

The Start Synchronization REQUEST event is used to notify the SCE that the synchronization process is about to start. The SCE uses this REQUEST to perform internal operations that are required for synchronization process preparation. This event has a push and a pull component.

Figure 3-15 Start Synchronization Event

Start Synchronization Event

End Synchronization Event

The End Synchronization REQUEST event is used to notify the SCE that the synchronization process has ended. This event has a push and a pull component.

Figure 3-16 End Synchronization Event

End Synchronization Event

Get Subscribers Events

During the SCE's Pull Model synchronization process, the Policy Server is required to retrieve ALL subscribers that the SCE is currently handling. The GET-SUBSCRIBERS-BULK-REQUEST event is a request from the Policy Server to the SCE to retrieve the next bulk of subscribers that the SCE is currently handling. Upon receiving this request, the SCE responds with the GET-SUBSCRIBERS-BULKRESPONSE event that supplies the subscriber names and Network-IDs.

Figure 3-17 Get Subscribers Event

Get Subscribers Event

For more information, see Pull Model, page 2-3 and Information About the Pull Model Synchronization Procedure, page 5-36.