Cisco SCMS SCE Subscriber API Programmer Guide, Release 4.0.x
Chapter: Application Programming Interface Events
Application Programming Interface Events
Introduction
This chapter describes the various events accessed by the Cisco Service Control Engine (SCE) Subscriber application programming interface (API).
It consists of the following sections:
API Events
The API accesses a set of events, which are a predefined set of messages that are passed back and forth between the policy server and the Cisco SCE platform as shown in Figure 3-1.
Figure 3-1 API Events Overview
Every message is assigned a type according to the purpose of the message:
•
Request—Requests information or performance of an action. Not all requests derive a response.
•Response—Answers a previous request.
•Indication—Indicates to the other side that an event occurred.
Most of the events can be used for both push and pull modes. See the "Subscriber Integration Modes" section.
The events are divided into the following subscriber provisioning process groups:
•Network ID management events—Includes events associated with modifying subscriber network ID mapping.
•Policy Profile management events—Includes events associated with modifying subscriber policy profile parameters.
•Quota management events—Includes events relating to the management of subscriber quota.
•Cisco SCE synchronization management events—Includes events associated with managing the Cisco SCE synchronization process.
You can perform bulk operations to bundle many triggers for the same event on subscribers to one global event.
The following sections describe each type of event:
•Cisco SCE Synchronization Procedure Events
Network ID Management Events
The following events are described in this section:
Login Events
Login events occur when a subscriber connects to the network. The events for pull and push modes differ.
Push Mode
The integration of Push Mode assumes that the Policy Server triggers introduction of the subscriber to the Cisco SCE. For example, the server receives a subscriber login indication from an external entity such as authentication, authorization, and accounting (AAA), extracts the required subscriber attributes, and pushes the information to the Cisco SCE platform as shown in Figure 3-2.
Figure 3-2 Login Events - Push Mode
The subscriber login operation either causes the creation of a new subscriber record in the Cisco SCE or updates an existing subscriber. For example, for cable modem networks, the subscriber is a cable modem and the customer premise equipments (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 adds the CPE IP address to the aubscriber network ID list.
Pull Mode
The integration of Pull Mode assumes that the Cisco 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 Cisco SCE initiates a request to the external system (a login-pull request) that either provides the subscriber login information (a login-pull reply) or is omitted when no information exists for this IP. The login information provided to the Cisco SCE replaces the anonymous subscriber with the actual subscriber and enforces the correct policy as shown in Figure 3-3.
If the external system rejects the login and the traffic continues from the anonymous subscriber, the Cisco SCE retries the pull request.
Figure 3-3 Login Events - Pull Mode
Note Despite being classified as network ID management event, LOGIN-REQUEST and LOGIN-PULL-RESPONSE events are optimized to allow sending all subscriber information to the Cisco SCE. Use these events for policy profile and quota updates when a single policy server performs all parts of subscriber provisioning. For topologies that include multiple policy servers, use separate events to update policy profile and quota information, as described in the following sections. For more information about topologies, see the "Supported Topologies" section.
Logout Events
The logout event indicates that the subscriber no longer uses a certain network ID. A logout event might not result in the removal of the subscriber record from the Cisco SCE as shown in Figure 3-4. For example, in cable modem networks, when there is more than one CPE item connected to the same modem, the logout of one CPE might not lead to the removal of a subscriber if another CPE remains connected. The subscriber is removed when all the CPEs (subscriber network IDs) are disconnected.
Figure 3-4 Logout Request Event
The logout event in Pull Mode might occur, for example, when the Cisco SCE detects that the subscriber is not active for a specific time interval. The Cisco SCE logs out the subscriber and sends a LOGOUT-INDICATION event as shown in Figure 3-5.
Figure 3-5 Logout Indication Event
The LOGOUT-INDICATION event can also follow the Logout operation. This sequence of actions occurs when a subscriber is removed, for example, when no more valid network mappings (IP) are associated with this subscriber as shown in Figure 3-6.
Figure 3-6 Logout Request Event
Network ID Update Event
The network update event is a REQUEST from the Policy Server to the Cisco SCE to update the network ID of the subscriber that exists in the Cisco SCE platform as shown in Figure 3-7. This event does not require any RESPONSE.
Figure 3-7 Network ID Update Event
Policy Profile Management
The policy profile management consists of one event, namely, profile update event.
Profile Update
The profile update event is a REQUEST from the policy server to the Cisco SCE to update the policy profile of the subscriber that exists in the Cisco SCE platform as shown in Figure 3-8. This event does not require any RESPONSE.
Figure 3-8 Profile Update Event
Note The LOGIN-REQUEST event and LOGIN-PULL-RESPONSE event can also update the policy profile.
Quota Management
This section consists of these topics:
Quota Update
The Quota Update event is a REQUEST from the policy server to the Cisco SCE to update the quota of the subscriber that exists in the Cisco SCE platform as shown in Figure 3-9. This event does not require any RESPONSE event.
Figure 3-9 Quota Update Event
Note The LOGIN-REQUEST event and LOGIN-PULL-RESPONSE event can also update the quota.
Get Quota Status
The Get Quota Status event is a REQUEST from the policy server to the Cisco SCE to report the quota information of the subscriber that exists in the Cisco SCE platform as shown in Figure 3-10. A QUOTA-STATUS-INDICATION event follows this event.
Figure 3-10 Get Quota Status Event
Note The Cisco SCE can issue a QUOTA-STATUS-INDICATION event periodically without a specific request from the policy server. See the "Quota Status" section.
Quota Status
The Cisco SCE uses the quota status INDICATION event to notify the policy server about the remaining quota as shown in Figure 3-11. This event is invoked periodically according to a preconfigured time interval.
Figure 3-11 Quota Status Event
Quota Below Threshold
The Cisco 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 as shown in Figure 3-12. An UPDATE-QUOTA-REQUEST event from the policy server to the Cisco SCE can follow this event, but is not mandatory.
Figure 3-12 Quota Below Threshold Event
Quota Depleted
The Cisco SCE uses the quota depleted INDICATION event to notify the policy server that the quota for certain services of the specific subscriber is depleted as shown in Figure 3-13. An UPDATE-QUOTA-REQUEST event from the policy server to the Cisco SCE can follow this event.
Figure 3-13 Quota Depleted Event
Quota State Restore
The quota state restore event is an INDICATION from the Cisco SCE to the policy server to restore the quota of the subscriber that exists in the Cisco SCE platform as shown in Figure 3-14. This event is invoked immediately after a subscriber logs in to the Cisco SCE. A quota update event from the Policy Server can follow this event.
Figure 3-14 Quota State Restore Event
Cisco SCE Synchronization Procedure Events
This section consists of these topics:
Start Synchronization
The start synchronization REQUEST event notifies the Cisco SCE that the synchronization process is about to start as shown in Figure 3-15. The Cisco SCE uses this REQUEST to perform internal operations that are required to prepare for synchronization. This event has a push and a pull component.
Figure 3-15 Start Synchronization Event
End Synchronization
The End Synchronization REQUEST event notifies the Cisco SCE that the synchronization process ended as shown in Figure 3-16. This event has a push and a pull component.
Figure 3-16 End Synchronization Event
Get Subscribers
During a Cisco SCE Pull Mode synchronization process, the policy server is required to retrieve all subscribers that the Cisco SCE is currently managing. The policy server sends the GET-SUBSCRIBERS-BULK-REQUEST event to the Cisco SCE to retrieve the next bulk of subscribers that the Cisco SCE is currently managing. When the Cisco SCE receives this request, it responds with the GET-SUBSCRIBERS-BULK-RESPONSE event that supplies the subscriber names and network IDs as shown in Figure 3-17.
Figure 3-17 Get Subscribers Event
For more information, see the "Pull Mode" section and the "Pull Mode Synchronization Procedure" section.
Feedback