Application Programming Interface Events
Revised: November 8, 2010, OL-21083-02
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 as shown in Figure 3-1.
Figure 3-1 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 modes. See the "Information About Subscriber Integration Modes" section.
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
•Information About SCE Synchronization Procedure Events
Information About Network ID Management Events
•Information About Login 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 modes.
The Push mode integration 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 Authorization, Authentication, and Accounting (AAA), extracts the required subscriber attributes, and pushes the information to the SCE platform as shown in Figure 3-2.
Figure 3-2 Login Events - Push Mode
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 Network ID list.
The Pull mode integration 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 as shown in Figure 3-3.
If the external system rejects the login and the traffic keeps coming from the anonymous subscriber, the pull request is retried.
Figure 3-3 Login Events - Pull Mode
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" section.
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 as shown in Figure 3-4. For example, in cable modem networks, when there is more than one Customer Premise Equipment (CPE) items 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 Network-IDs) are disconnected.
Figure 3-4 Logout Request Event
The logout event in the Pull mode 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 as shown in Figure 3-5.
Figure 3-5 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 as shown in Figure 3-6.
Figure 3-6 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 as shown in Figure 3-7. This event does not require any RESPONSE.
Figure 3-7 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 as shown in Figure 3-8. This event does not require any RESPONSE.
Figure 3-8 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
•Get Quota Status
•Quota Below Threshold
•Quota State Restore
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 as shown in Figure 3-9. This event does not require any RESPONSE event.
Figure 3-9 Quota Update Event
Note As described above, 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 SCE to report the quota information of the subscriber that already exists in the SCE platform as shown in Figure 3-10. A QUOTA-STATUS-INDICATION event follows this event.
Figure 3-10 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 the "Quota Status" section.
The 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 in a preconfigured time interval.
Figure 3-11 Quota Status Event
Quota Below Threshold
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 as shown in Figure 3-12. 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
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 as shown in Figure 3-13. An UPDATE-QUOTA-REQUEST event from the Policy Server to the SCE may follow this event.
Figure 3-13 Quota Depleted Event
Quota State Restore
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 as shown in Figure 3-14. 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
Information About SCE Synchronization Procedure Events
The Start Synchronization REQUEST event is used to notify the SCE that the synchronization process is about to start as shown in Figure 3-15. 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
The End Synchronization REQUEST event is used to notify the SCE that the synchronization process has ended as shown in Figure 3-16. This event has a push and a pull component.
Figure 3-16 End Synchronization Event
During the SCEs Pull mode 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 as shown in Figure 3-17.
Figure 3-17 Get Subscribers Event
For more information, see the "Pull Mode" section and the "Information About the Pull Mode Synchronization Procedure" section.