Application Programming Interface Events
Revised: July 28, 2009, OL-8236-08
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
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
•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.
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
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.
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
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.
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
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
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
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
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
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
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
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 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 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 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
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
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
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
For more information, see Pull Model, page 2-3 and Information About the Pull Model Synchronization Procedure, page 5-36.