Application Programming Interface Events
Revised: December 21, 2012, OL-26793-02
This chapter describes the various events accessed by the Service Control Management Suite (SCMS) Service Control Engine (SCE) Subscriber application programming interface (API).
It consists of the following sections:
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 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.
•SCE synchronization management events—Includes events associated with managing the 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:
•Network ID Management Events
•Policy Profile Management
•SCE Synchronization Procedure Events
Network ID Management Events
The following events are described in this section:
•Network ID Update Event
Login events occur when a subscriber connects to the network. The events for pull and push modes differ.
The integration of Push Mode assumes that the Policy Server triggers introduction of the subscriber to the 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 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 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.
The integration of Pull Mode 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 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 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 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 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.
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 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 SCE detects 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 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 SCE to update the network ID of the subscriber that 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
Policy Profile Management
The policy profile management consists of one event, namely, profile update event.
The profile update event is a REQUEST from the policy server to the SCE to update the policy profile of the subscriber that 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 The LOGIN-REQUEST event and LOGIN-PULL-RESPONSE event can also update the policy profile.
This section consists of these topics:
•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 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 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 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 The SCE can issue a QUOTA-STATUS-INDICATION event periodically 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 according to 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 can follow this event, but 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 can 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 logs in to the SCE. A quota update event from the Policy Server can follow this event.
Figure 3-14 Quota State Restore Event
SCE Synchronization Procedure Events
This section consists of these topics:
The start synchronization REQUEST event notifies 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 to prepare for synchronization. This event has a push and a pull component.
Figure 3-15 Start Synchronization Event
The End Synchronization REQUEST event notifies the 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
During an SCE Pull Mode synchronization process, the policy server is required to retrieve all subscribers that the SCE is currently managing. The policy server sends the GET-SUBSCRIBERS-BULK-REQUEST event to the SCE to retrieve the next bulk of subscribers that the SCE is currently managing. When the 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.